add tags to swagger

developer-docs/docs.json

@@ -16,7 +16,7 @@
     "tabs": [
       {
         "tab": "API Documentation",
-        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/2b043e54604b70715a9e7d0a9a7836763174a126/swagger/swagger.json"
+        "openapi": "https://raw.githubusercontent.com/chatwoot/chatwoot/90c600acd94cfe2f5c41d5cedebdec9534cba2d7/swagger/swagger.json"
       }
     ]
   },

docker-compose.yaml

@@ -92,7 +92,7 @@ services:
     environment:
       - POSTGRES_DB=chatwoot
       - POSTGRES_USER=postgres
-      - POSTGRES_PASSWORD=
+      - POSTGRES_PASSWORD=postgres
 
   redis:
     image: redis:alpine

docs/api-reference/application.mdx

@@ -0,0 +1,70 @@
+---
+title: 'Application API'
+description: 'API endpoints for managing application-level resources'
+---
+
+# Application API
+
+The Application API provides endpoints for managing application-level resources in Chatwoot, including contacts, conversations, inboxes, messages, and more.
+
+<Note>
+These APIs require a user API access token (`userApiKey`) for authentication.
+</Note>
+
+## Available Endpoints
+
+The Application API includes endpoints for:
+
+- **Account AgentBots** - Managing agent bots within accounts
+- **Agents** - Managing agents
+- **Canned Responses** - Managing canned responses
+- **Contacts** - Managing contacts
+- **Conversations** - Managing conversations
+- **Custom Attributes** - Managing custom attributes
+- **Custom Filters** - Managing custom filters
+- **Inboxes** - Managing inboxes
+- **Integrations** - Managing integrations
+- **Messages** - Managing messages
+- **Profile** - Managing user profile
+- **Reports** - Generating reports
+- **Teams** - Managing teams
+- **Webhooks** - Managing webhooks
+- **Automation Rules** - Managing automation rules
+- **Help Center** - Managing help center
+
+## Authentication
+
+Application API endpoints require the user API access token:
+
+```bash
+curl -X GET "https://app.chatwoot.com/api/v1/accounts/{account_id}/inboxes" \
+  -H "api_access_token: your_user_api_token"
+```
+
+## Rate Limiting
+
+Application API requests are subject to rate limiting. Implement appropriate retry logic in your applications.
+
+## OpenAPI Specification
+
+The complete OpenAPI specification for the Application API is available below:
+
+<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/application">
+  View the complete OpenAPI specification for the Application API
+</Card>
+
+## Code Examples
+
+```javascript
+// Example: Fetching all inboxes in an account
+const response = await fetch('https://app.chatwoot.com/api/v1/accounts/1/inboxes', {
+  method: 'GET',
+  headers: {
+    'Content-Type': 'application/json',
+    'api_access_token': 'your_user_api_token'
+  }
+});
+
+const data = await response.json();
+console.log(data);
+``` 

docs/api-reference/client.mdx

@@ -0,0 +1,55 @@
+---
+title: 'Client API'
+description: 'API endpoints for client applications'
+---
+
+# Client API
+
+The Client API provides endpoints for client applications to interact with Chatwoot, including managing contacts, conversations, and messages.
+
+<Note>
+Some of these APIs may not require authentication, while others may use alternative authentication methods.
+</Note>
+
+## Available Endpoints
+
+The Client API includes endpoints for:
+
+- **Contacts API** - APIs for managing contacts from client applications
+- **Conversations API** - APIs for managing conversations from client applications
+- **Messages API** - APIs for managing messages from client applications
+
+## Authentication
+
+Authentication requirements vary by endpoint. Refer to the specific endpoint documentation for details.
+
+## Rate Limiting
+
+Client API requests are subject to rate limiting. Implement appropriate retry logic in your applications.
+
+## OpenAPI Specification
+
+The complete OpenAPI specification for the Client API is available below:
+
+<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/client">
+  View the complete OpenAPI specification for the Client API
+</Card>
+
+## Code Examples
+
+```javascript
+// Example: Creating a contact using the Client API
+const response = await fetch('https://app.chatwoot.com/public/api/v1/inboxes/{inbox_identifier}/contacts', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    name: 'John Doe',
+    email: 'john@example.com'
+  })
+});
+
+const data = await response.json();
+console.log(data);
+``` 

docs/api-reference/other.mdx

@@ -0,0 +1,45 @@
+---
+title: 'Other APIs'
+description: 'Additional API endpoints'
+---
+
+# Other APIs
+
+This section covers additional API endpoints in Chatwoot that don't fit neatly into the other categories.
+
+## Available Endpoints
+
+The Other APIs include endpoints for:
+
+- **CSAT Survey Page** - APIs for CSAT survey functionality
+
+## Authentication
+
+Authentication requirements vary by endpoint. Refer to the specific endpoint documentation for details.
+
+## Rate Limiting
+
+API requests are subject to rate limiting. Implement appropriate retry logic in your applications.
+
+## OpenAPI Specification
+
+The complete OpenAPI specification for the Other APIs is available below:
+
+<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/other">
+  View the complete OpenAPI specification for the Other APIs
+</Card>
+
+## Code Examples
+
+```javascript
+// Example: Retrieving survey responses
+const response = await fetch('https://app.chatwoot.com/survey/responses/{conversation_uuid}', {
+  method: 'GET',
+  headers: {
+    'Content-Type': 'application/json'
+  }
+});
+
+const data = await response.json();
+console.log(data);
+``` 

docs/api-reference/platform.mdx

@@ -0,0 +1,61 @@
+---
+title: 'Platform API'
+description: 'API endpoints for managing platform-level resources'
+---
+
+# Platform API
+
+The Platform API provides endpoints for managing platform-level resources in Chatwoot, including accounts, account users, agent bots, and users.
+
+<Note>
+These APIs require a platform app API access token (`platformAppApiKey`) for authentication.
+</Note>
+
+## Available Endpoints
+
+The Platform API includes endpoints for:
+
+- **Accounts** - Creating, updating, retrieving, and deleting accounts
+- **Account Users** - Managing users within accounts
+- **AgentBots** - Creating and managing agent bots at the platform level
+- **Users** - Creating, updating, retrieving, and deleting users
+
+## Authentication
+
+Platform API endpoints require the platform app API access token:
+
+```bash
+curl -X GET "https://app.chatwoot.com/platform/api/v1/accounts" \
+  -H "api_access_token: your_platform_app_api_token"
+```
+
+## Rate Limiting
+
+Platform API requests are subject to rate limiting. Implement appropriate retry logic in your applications.
+
+## OpenAPI Specification
+
+The complete OpenAPI specification for the Platform API is available below:
+
+<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/platform">
+  View the complete OpenAPI specification for the Platform API
+</Card>
+
+## Code Examples
+
+```javascript
+// Example: Creating a new account using the Platform API
+const response = await fetch('https://app.chatwoot.com/platform/api/v1/accounts', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'api_access_token': 'your_platform_app_api_token'
+  },
+  body: JSON.stringify({
+    name: 'New Account'
+  })
+});
+
+const data = await response.json();
+console.log(data);
+``` 

docs/authentication.mdx

@@ -0,0 +1,44 @@
+---
+title: 'Authentication'
+description: 'Learn how to authenticate with the Chatwoot API'
+---
+
+# Authentication
+
+All API requests to Chatwoot require authentication. Chatwoot uses API access tokens for authentication.
+
+## API Access Tokens
+
+### User API Access Token
+
+This token can be obtained from your profile page in the Chatwoot dashboard. It provides access to endpoints based on your user permission levels.
+
+```bash
+curl -X GET "https://app.chatwoot.com/api/v1/profile" \
+  -H "api_access_token: your_api_access_token"
+```
+
+### Agent Bot API Access Token
+
+This token should be provided by a system admin or obtained via the Rails console. It can be used to build bot integrations and can only access limited APIs.
+
+### Platform App API Access Token
+
+This token can be obtained by the system admin after creating a platform app. It should be used to provision agent bots, accounts, users, and their roles.
+
+## Adding Authentication to Requests
+
+Include your API access token in the request header:
+
+```bash
+curl -X GET "https://app.chatwoot.com/api/v1/accounts/{account_id}/inboxes" \
+  -H "api_access_token: your_api_access_token"
+```
+
+## Security Best Practices
+
+- Keep your API access tokens secure
+- Rotate your tokens periodically
+- Use HTTPS for all API requests
+- Only grant the minimum required permissions
+- Don't expose tokens in client-side code 

docs/errors.mdx

@@ -0,0 +1,60 @@
+---
+title: 'Error Handling'
+description: 'Learn about error responses from the Chatwoot API'
+---
+
+# Error Handling
+
+When using the Chatwoot API, you may encounter various error responses. This guide helps you understand and handle these errors effectively.
+
+## HTTP Status Codes
+
+Chatwoot APIs use standard HTTP status codes to indicate the success or failure of a request:
+
+| Status Code | Description |
+|-------------|-------------|
+| 200 OK | The request was successful |
+| 201 Created | The resource was successfully created |
+| 400 Bad Request | The request was invalid or cannot be served |
+| 401 Unauthorized | Authentication failed or user doesn't have permissions |
+| 403 Forbidden | The authenticated user doesn't have access to the requested resource |
+| 404 Not Found | The requested resource doesn't exist |
+| 422 Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors |
+| 429 Too Many Requests | Too many requests, rate limiting applied |
+| 500 Internal Server Error | Something went wrong on our servers |
+
+## Error Response Format
+
+Error responses include a JSON object with an error message:
+
+```json
+{
+  "error": "Invalid login credentials"
+}
+```
+
+## Common Error Scenarios
+
+### Authentication Errors
+
+- **401 Unauthorized**: Invalid or missing API access token
+- **403 Forbidden**: Insufficient permissions for the requested operation
+
+### Resource Errors
+
+- **404 Not Found**: The requested resource does not exist
+- **422 Unprocessable Entity**: The request contained invalid data
+
+### Rate Limiting
+
+- **429 Too Many Requests**: You've exceeded the API rate limits
+
+## Handling Errors
+
+When building integrations with Chatwoot, always:
+
+1. Check HTTP status codes
+2. Parse error messages
+3. Implement appropriate retry logic
+4. Log errors for debugging
+5. Provide meaningful error messages to users 

docs/introduction.mdx

@@ -0,0 +1,33 @@
+---
+title: 'Chatwoot API Documentation'
+description: 'Welcome to the Chatwoot API Documentation'
+---
+
+# Introduction to Chatwoot API
+
+Chatwoot provides comprehensive API endpoints to manage and integrate with all aspects of the platform. Use these APIs to create custom integrations, automate workflows, and build on top of Chatwoot.
+
+## Getting Started
+
+To use the Chatwoot API, you'll need:
+
+1. A Chatwoot account
+2. An API access token (obtained from your profile page)
+3. Basic understanding of RESTful APIs and HTTP requests
+
+## API Organization
+
+Our APIs are organized into several logical groups:
+
+- **Platform API** - For managing platform-level resources like accounts, users, and agent bots
+- **Application API** - For working with application-level resources like contacts, conversations, and inboxes
+- **Client API** - For client applications to interact with Chatwoot
+- **Other APIs** - Additional functionality like CSAT surveys
+
+## Authentication
+
+All API requests require authentication. See the [Authentication](/authentication) section for details.
+
+## Rate Limiting
+
+API requests are subject to rate limiting. Please implement appropriate retry logic in your applications. 

lib/tasks/swagger.rake

@@ -17,6 +17,61 @@ namespace :swagger do
       puts 'Swagger build was successful.'
       puts "Generated #{base_path}/swagger.json"
       puts 'Go to http://localhost:3000/swagger see the changes.'
+      
+      # Build tag group specific swagger files
+      Rake::Task['swagger:build_tag_groups'].invoke
     end
   end
+  
+  desc 'build separate swagger files for each tag group'
+  task build_tag_groups: :environment do
+    require 'json_refs'
+    
+    base_path = Rails.root.join('swagger')
+    tag_groups_path = base_path.join('tag_groups')
+    
+    Dir.chdir(tag_groups_path) do
+      # Build for platform
+      platform_yaml = YAML.safe_load(File.open('platform.yml'))
+      platform_build = JsonRefs.call(
+        platform_yaml,
+        resolve_local_ref: false,
+        resolve_file_ref: true,
+        logging: true
+      )
+      File.write('platform_swagger.json', JSON.pretty_generate(platform_build))
+      
+      # Build for application
+      application_yaml = YAML.safe_load(File.open('application.yml'))
+      application_build = JsonRefs.call(
+        application_yaml,
+        resolve_local_ref: false,
+        resolve_file_ref: true,
+        logging: true
+      )
+      File.write('application_swagger.json', JSON.pretty_generate(application_build))
+      
+      # Build for client
+      client_yaml = YAML.safe_load(File.open('client.yml'))
+      client_build = JsonRefs.call(
+        client_yaml,
+        resolve_local_ref: false,
+        resolve_file_ref: true,
+        logging: true
+      )
+      File.write('client_swagger.json', JSON.pretty_generate(client_build))
+      
+      # Build for others
+      others_yaml = YAML.safe_load(File.open('others.yml'))
+      others_build = JsonRefs.call(
+        others_yaml,
+        resolve_local_ref: false,
+        resolve_file_ref: true,
+        logging: true
+      )
+      File.write('other_swagger.json', JSON.pretty_generate(others_build))
+    end
+    
+    puts 'Tag-specific swagger files generated successfully.'
+  end
 end

swagger/tag_groups/application.yml

@@ -0,0 +1,59 @@
+openapi: '3.0.4'
+info:
+  title: Chatwoot - Application API
+  description: Application API endpoints for Chatwoot
+  version: 1.1.0
+  termsOfService: https://www.chatwoot.com/terms-of-service/
+  contact:
+    email: hello@chatwoot.com
+  license:
+    name: MIT License
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: https://app.chatwoot.com/
+tags:
+  - name: Account AgentBots
+    description: Manage agent bots within accounts
+  - name: Agents
+    description: Manage agents
+  - name: Canned Responses
+    description: Manage canned responses
+  - name: Contacts
+    description: Manage contacts
+  - name: Conversations
+    description: Manage conversations
+  - name: Custom Attributes
+    description: Manage custom attributes
+  - name: Custom Filters
+    description: Manage custom filters
+  - name: Inboxes
+    description: Manage inboxes
+  - name: Integrations
+    description: Manage integrations
+  - name: Messages
+    description: Manage messages
+  - name: Profile
+    description: Manage user profile
+  - name: Reports
+    description: Generate reports
+  - name: Teams
+    description: Manage teams
+  - name: Webhooks
+    description: Manage webhooks
+  - name: Automation Rule
+    description: Manage automation rules
+  - name: Help Center
+    description: Manage help center
+paths:
+  $ref: ../paths/index.yml
+components:
+  schemas:
+    $ref: ../definitions/index.yml
+  parameters:
+    $ref: ../parameters/index.yml
+  securitySchemes:
+    userApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. 

swagger/tag_groups/client.yml

@@ -0,0 +1,33 @@
+openapi: '3.0.4'
+info:
+  title: Chatwoot - Client API
+  description: Client API endpoints for Chatwoot
+  version: 1.1.0
+  termsOfService: https://www.chatwoot.com/terms-of-service/
+  contact:
+    email: hello@chatwoot.com
+  license:
+    name: MIT License
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: https://app.chatwoot.com/
+tags:
+  - name: Contacts API
+    description: APIs for managing contacts from client applications
+  - name: Conversations API
+    description: APIs for managing conversations from client applications
+  - name: Messages API
+    description: APIs for managing messages from client applications
+paths:
+  $ref: ../paths/index.yml
+components:
+  schemas:
+    $ref: ../definitions/index.yml
+  parameters:
+    $ref: ../parameters/index.yml
+  securitySchemes:
+    userApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. 

swagger/tag_groups/others.yml

@@ -0,0 +1,29 @@
+openapi: '3.0.4'
+info:
+  title: Chatwoot - Other APIs
+  description: Other API endpoints for Chatwoot
+  version: 1.1.0
+  termsOfService: https://www.chatwoot.com/terms-of-service/
+  contact:
+    email: hello@chatwoot.com
+  license:
+    name: MIT License
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: https://app.chatwoot.com/
+tags:
+  - name: CSAT Survey Page
+    description: APIs for CSAT survey functionality
+paths:
+  $ref: ../paths/index.yml
+components:
+  schemas:
+    $ref: ../definitions/index.yml
+  parameters:
+    $ref: ../parameters/index.yml
+  securitySchemes:
+    userApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. 

swagger/tag_groups/platform.yml

@@ -0,0 +1,40 @@
+openapi: '3.0.4'
+info:
+  title: Chatwoot - Platform API
+  description: Platform API endpoints for Chatwoot
+  version: 1.1.0
+  termsOfService: https://www.chatwoot.com/terms-of-service/
+  contact:
+    email: hello@chatwoot.com
+  license:
+    name: MIT License
+    url: https://opensource.org/licenses/MIT
+servers:
+  - url: https://app.chatwoot.com/
+tags:
+  - name: Accounts
+    description: Platform account management
+  - name: Account Users
+    description: Manage users within platform accounts
+  - name: AgentBots
+    description: Manage agent bots on the platform
+  - name: Users
+    description: Platform user management
+paths:
+  $ref: ../paths/index.yml
+components:
+  schemas:
+    $ref: ../definitions/index.yml
+  parameters:
+    $ref: ../parameters/index.yml
+  securitySchemes:
+    userApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels.
+    platformAppApiKey:
+      type: apiKey
+      in: header
+      name: api_access_token
+      description: This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles.