openapi: 3.0.4 info: title: Evolution Foundation - CRM Service - Conversations description: Management of contacts, conversations, inboxes, labels and macros version: 1.1.0 servers: - url: https://api.evoai.app description: Production server - url: http://localhost:3000 description: Development server variables: port: default: '3000' - url: '{customUrl}' description: Custom server variables: customUrl: default: https://your-instance.com description: Enter your server URL paths: /api/v1/conversations: parameters: [] get: operationId: conversationList description: List all the conversations with pagination summary: Conversations List security: - userApiKey: [] parameters: - name: assignee_type in: query schema: type: string enum: - me - unassigned - all - assigned default: all description: Filter conversations by assignee type. - name: status in: query schema: type: string enum: - all - open - resolved - pending - snoozed default: open description: Filter by conversation status. - name: q in: query schema: type: string description: Filters conversations with messages containing the search term - name: inbox_id in: query schema: type: integer - name: team_id in: query schema: type: integer - name: labels in: query schema: type: array items: type: string - name: page in: query schema: type: integer default: 1 description: paginate through conversations responses: '200': description: Conversations retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of conversations items: $ref: '#/components/schemas/conversation' meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 20 total: type: integer description: Total number of conversations example: 100 totalPages: type: integer description: Total number of pages example: 5 hasNextPage: type: boolean nullable: true description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversations retrieved successfully example: success: true data: [] meta: pagination: page: 1 pageSize: 20 total: 0 totalPages: 0 hasNextPage: null hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Conversations retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: GET post: operationId: newConversation summary: Create New Conversation description: "Creating a conversation in Evolution requires a source id. \n\n Learn more about source_id: https://evoai.app/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel" security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/conversation_create_payload' responses: '200': description: Conversation created successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Created conversation data properties: id: type: string format: uuid description: ID of the conversation account_id: type: string format: uuid description: Account ID inbox_id: type: string format: uuid description: ID of the inbox meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation created successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 account_id: 123e4567-e89b-12d3-a456-426614174000 inbox_id: 660e8400-e29b-41d4-a716-446655440001 meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation created successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access denied value: success: false error: code: FORBIDDEN message: Access denied meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: source_id: - Source ID is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations method: POST /api/v1/conversations/available_for_pipeline: get: operationId: getAvailableForPipeline summary: Get Conversations Available for Pipeline description: Returns conversations that can be added to pipelines security: - userApiKey: [] parameters: - name: pipeline_id in: query schema: type: integer description: Filter by pipeline ID responses: '200': description: Conversations available for pipeline retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of conversations available for pipeline items: $ref: '#/components/schemas/conversation_show' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversations available for pipeline retrieved successfully example: success: true data: [] meta: timestamp: '2024-01-15T10:30:00Z' message: Conversations available for pipeline retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/available_for_pipeline method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/available_for_pipeline method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/available_for_pipeline method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/available_for_pipeline method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/available_for_pipeline method: GET /api/v1/conversations/filter: parameters: [] post: operationId: conversationFilter description: Filter conversations with custom filter options and pagination summary: Conversations Filter security: - userApiKey: [] parameters: - name: page in: query schema: type: number requestBody: required: true content: application/json: schema: type: object properties: payload: type: array items: type: object properties: attribute_key: type: string description: filter attribute name filter_operator: type: string description: filter operator name enum: - equal_to - not_equal_to - contains - does_not_contain values: type: array items: type: string description: array of the attribute values to filter query_operator: type: string description: query operator name enum: - AND - OR example: - attribute_key: browser_language filter_operator: not_equal_to values: - en query_operator: AND - attribute_key: status filter_operator: equal_to values: - pending query_operator: null responses: '200': description: Conversations filtered successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of filtered conversations items: $ref: '#/components/schemas/conversation' meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 20 total: type: integer description: Total number of conversations example: 100 totalPages: type: integer description: Total number of pages example: 5 hasNextPage: type: boolean nullable: true description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversations filtered successfully example: success: true data: [] meta: pagination: page: 1 pageSize: 20 total: 0 totalPages: 0 hasNextPage: null hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Conversations filtered successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/filter method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/filter method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/filter method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/filter method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/filter method: POST /api/v1/conversations/meta: parameters: [] get: operationId: conversationListMeta description: Get open, unassigned and all Conversation counts summary: Get Conversation Counts security: - userApiKey: [] parameters: - name: status in: query schema: type: string enum: - all - open - resolved - pending - snoozed default: open description: Filter by conversation status. - name: q in: query schema: type: string description: Filters conversations with messages containing the search term - name: inbox_id in: query schema: type: integer - name: team_id in: query schema: type: integer - name: labels in: query schema: type: array items: type: string responses: '200': description: Conversation counts retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Conversation counts data properties: mine_count: type: number description: Count of conversations assigned to current user example: 5 unassigned_count: type: number description: Count of unassigned conversations example: 10 assigned_count: type: number description: Count of assigned conversations example: 15 all_count: type: number description: Total count of conversations example: 30 meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation counts retrieved successfully example: success: true data: mine_count: 5 unassigned_count: 10 assigned_count: 15 all_count: 30 meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation counts retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/meta method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/meta method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/meta method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/meta method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/meta method: GET /api/v1/conversations/search: get: operationId: searchConversations summary: Search Conversations description: Search conversations using a search term security: - userApiKey: [] parameters: - name: q in: query required: true schema: type: string description: Search term for conversations - name: page in: query schema: type: integer default: 1 responses: '200': description: Conversations retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of conversations matching the search term items: $ref: '#/components/schemas/conversation' meta: type: object properties: pagination: type: object properties: page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 20 total: type: integer description: Total number of conversations example: 100 totalPages: type: integer description: Total number of pages example: 5 hasNextPage: type: boolean nullable: true description: Whether there is a next page example: true hasPreviousPage: type: boolean nullable: true description: Whether there is a previous page example: null timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversations retrieved successfully example: success: true data: [] meta: pagination: page: 1 pageSize: 20 total: 0 totalPages: 0 hasNextPage: null hasPreviousPage: null timestamp: '2024-01-15T10:30:00Z' message: Conversations retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/search method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/search method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/search method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: summary: Resource not found value: success: false error: code: NOT_FOUND message: Resource not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/search method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/search method: GET /api/v1/conversations/{conversation_id}: parameters: - $ref: '#/components/parameters/conversation_id' get: operationId: get-details-of-a-conversation summary: Conversation Details security: - userApiKey: [] description: Get all details regarding a conversation with all messages in the conversation responses: '200': description: Conversation details retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/conversation_show' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation details retrieved successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 account_id: 123e4567-e89b-12d3-a456-426614174000 inbox_id: 660e8400-e29b-41d4-a716-446655440001 meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation details retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Access denied value: success: false error: code: FORBIDDEN message: Access denied meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: GET patch: operationId: update-conversation summary: Update Conversation description: Update Conversation Attributes security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object properties: priority: type: string enum: - urgent - high - medium - low - none description: The priority of the conversation example: high responses: '200': description: Conversation updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/conversation_show' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 account_id: 123e4567-e89b-12d3-a456-426614174000 inbox_id: 660e8400-e29b-41d4-a716-446655440001 priority: high meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: priority: - 'Priority must be one of: urgent, high, medium, low, none' meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id} method: PATCH /api/v1/conversations/{conversation_id}/assignments: parameters: - $ref: '#/components/parameters/conversation_id' post: operationId: assign-a-conversation summary: Assign Conversation description: Assign a conversation to an agent or a team security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object properties: assignee_id: type: string format: uuid description: Id of the assignee user example: 111e2222-e33b-44d5-a666-777888999000 team_id: type: string format: uuid description: Id of the team. If the assignee_id is present, this param would be ignored example: 555e6666-e77b-88d9-a000-111222333444 responses: '200': description: Conversation assigned successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: $ref: '#/components/schemas/user' meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation assigned successfully example: success: true data: id: 111e2222-e33b-44d5-a666-777888999000 name: John Doe email: john@example.com meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation assigned successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/assignments method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/assignments method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/assignments method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/assignments method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/assignments method: POST /api/v1/conversations/{conversation_id}/custom_attributes: parameters: - $ref: '#/components/parameters/conversation_id' post: operationId: update-custom-attributes-of-a-conversation summary: Update Custom Attributes description: Updates the custom attributes of a conversation security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - custom_attributes properties: custom_attributes: type: object description: The custom attributes to be set for the conversation example: order_id: '12345' previous_conversation: '67890' responses: '200': description: Conversation custom attributes updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Updated conversation data properties: id: type: string format: uuid description: ID of the conversation custom_attributes: type: object description: Updated custom attributes of the conversation additionalProperties: true meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation custom attributes updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 custom_attributes: order_id: '12345' previous_conversation: '67890' meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation custom attributes updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: custom_attributes: - Custom attributes must be an object meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/custom_attributes method: POST /api/v1/conversations/{conversation_id}/labels: parameters: - $ref: '#/components/parameters/conversation_id' get: operationId: list-all-labels-of-a-conversation summary: List Labels security: - userApiKey: [] description: Lists all the labels of a conversation responses: '200': description: Conversation labels retrieved successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of label strings items: type: string meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation labels retrieved successfully example: success: true data: - vip - priority - newsletter meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation labels retrieved successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: GET '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: GET '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: GET '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: GET '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: GET post: operationId: conversation-add-labels summary: Add Labels security: - userApiKey: [] description: Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation. requestBody: required: true content: application/json: schema: type: object required: - labels properties: labels: type: array description: Array of labels (comma-separated strings) items: type: string example: - support - billing responses: '200': description: Conversation labels updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: array description: Array of label strings items: type: string meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation labels updated successfully example: success: true data: - support - billing meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation labels updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: labels: - Labels must be an array meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/labels method: POST /api/v1/conversations/{conversation_id}/messages: parameters: - $ref: '#/components/parameters/conversation_id' post: operationId: createMessage summary: Create Message description: Creates a new message in the conversation security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string description: Message content example: Hello, how can I help you? message_type: type: string enum: - outgoing - incoming default: outgoing private: type: boolean default: false description: If true, creates a private note content_type: type: string enum: - text - input_select - cards - form - article default: text content_attributes: type: object description: Additional content attributes examples: basic_message: summary: Basic text message value: content: Hello, how are you? message_type: outgoing private: false content_type: text content_attributes: {} private_note: summary: Nota privada value: content: Nota interna para a equipe message_type: outgoing private: true content_type: text content_attributes: {} responses: '200': description: Message created successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Created message data properties: id: type: string format: uuid content: type: string message_type: type: string content_type: type: string conversation_id: type: string format: uuid created_at: type: string format: date-time meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Message created successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 content: Hello, how can I help you? message_type: outgoing content_type: text conversation_id: 660e8400-e29b-41d4-a716-446655440001 created_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Message created successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: content: - Content is required meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages method: POST /api/v1/conversations/{conversation_id}/messages/{id}: parameters: - $ref: '#/components/parameters/conversation_id' - name: id in: path required: true description: Message ID schema: type: string format: uuid patch: operationId: updateMessage summary: Update Message description: Updates a message in the conversation security: - userApiKey: [] requestBody: required: true content: application/json: schema: type: object properties: content: type: string description: Updated message content responses: '200': description: Message updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Updated message data properties: id: type: string format: uuid content: type: string updated_at: type: string format: date-time meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Message updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 content: Updated message content updated_at: '2024-01-15T10:30:00Z' meta: timestamp: '2024-01-15T10:30:00Z' message: Message updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: message_not_found: summary: Message not found value: success: false error: code: NOT_FOUND message: Message not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: content: - Content cannot be empty meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: PATCH delete: operationId: deleteMessage summary: Delete Message description: Deletes a message from the conversation security: - userApiKey: [] responses: '200': description: Message deleted successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Deleted message data (null for delete operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Message deleted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Message deleted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: DELETE '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: DELETE '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: DELETE '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: message_not_found: summary: Message not found value: success: false error: code: NOT_FOUND message: Message not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: DELETE '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id} method: DELETE /api/v1/conversations/{conversation_id}/messages/{id}/retry: post: operationId: retryMessage summary: Retry Failed Message description: Retries sending a failed message security: - userApiKey: [] parameters: - $ref: '#/components/parameters/conversation_id' - name: id in: path required: true description: Message ID schema: type: string format: uuid responses: '200': description: Message retry initiated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Retry operation data (null for async operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Message retry initiated successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Message retry initiated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id}/retry method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id}/retry method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id}/retry method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: message_not_found: summary: Message not found value: success: false error: code: NOT_FOUND message: Message not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id}/retry method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/messages/{id}/retry method: POST /api/v1/conversations/{conversation_id}/mute: post: operationId: muteConversation summary: Mute Conversation description: Mutes notifications for a conversation security: - userApiKey: [] parameters: - $ref: '#/components/parameters/conversation_id' responses: '200': description: Conversation muted successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Updated conversation data (null for mute operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation muted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation muted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/mute method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/mute method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/mute method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/mute method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/mute method: POST /api/v1/conversations/{conversation_id}/toggle_priority: parameters: - $ref: '#/components/parameters/conversation_id' post: operationId: toggle-priority-of-a-conversation summary: Toggle Priority description: Toggles the priority of conversation security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - priority properties: priority: type: string enum: - urgent - high - medium - low - none description: The priority of the conversation example: high responses: '200': description: Conversation priority updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Updated conversation data properties: id: type: string format: uuid description: ID of the conversation priority: type: string description: Updated priority of the conversation example: high meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation priority updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 priority: high meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation priority updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: priority: - 'Priority must be one of: urgent, high, medium, low, none' meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_priority method: POST /api/v1/conversations/{conversation_id}/toggle_status: parameters: - $ref: '#/components/parameters/conversation_id' post: operationId: toggle-status-of-a-conversation summary: Toggle Status description: Toggles the status of the conversation between open and resolved security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - open - resolved - pending description: The status of the conversation example: open responses: '200': description: Conversation status updated successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object description: Updated conversation data properties: id: type: string format: uuid description: ID of the conversation status: type: string description: Updated status of the conversation example: open meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation status updated successfully example: success: true data: id: 550e8400-e29b-41d4-a716-446655440000 status: open meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation status updated successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: status: - 'Status must be one of: open, resolved, pending' meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/toggle_status method: POST /api/v1/conversations/{conversation_id}/transcript: post: operationId: sendTranscript summary: Send Conversation Transcript description: Sends the conversation transcript via email security: - userApiKey: [] parameters: - $ref: '#/components/parameters/conversation_id' requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email description: Email address to send transcript to example: user@example.com responses: '200': description: Transcript sent successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Transcript sending data (null for async operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Transcript sent successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Transcript sent successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST '422': description: Unprocessable Entity (validation error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Validation failed value: success: false error: code: VALIDATION_ERROR message: Validation failed details: email: - Email is required - Email must be a valid email address meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/transcript method: POST /api/v1/conversations/{conversation_id}/unmute: post: operationId: unmuteConversation summary: Unmute Conversation description: Unmutes notifications for a conversation security: - userApiKey: [] parameters: - $ref: '#/components/parameters/conversation_id' responses: '200': description: Conversation unmuted successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Updated conversation data (null for unmute operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation unmuted successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation unmuted successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unmute method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unmute method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unmute method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unmute method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unmute method: POST /api/v1/conversations/{conversation_id}/unread: post: operationId: markAsUnread summary: Mark Conversation as Unread description: Marks the conversation as unread for the agent security: - userApiKey: [] parameters: - $ref: '#/components/parameters/conversation_id' responses: '200': description: Conversation marked as unread successfully content: application/json: schema: type: object required: - success - data - meta - message properties: success: type: boolean example: true data: type: object nullable: true description: Updated conversation data (null for mark operations) example: null meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2024-01-15T10:30:00Z' message: type: string description: Success message example: Conversation marked as unread successfully example: success: true data: null meta: timestamp: '2024-01-15T10:30:00Z' message: Conversation marked as unread successfully '400': description: Bad Request (invalid data) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: summary: Invalid request parameters value: success: false error: code: VALIDATION_ERROR message: Invalid request parameters meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unread method: POST '401': description: Unauthorized (invalid or missing token) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_token: summary: Invalid or missing token value: success: false error: code: INVALID_TOKEN message: Invalid or missing authentication token meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unread method: POST '403': description: Forbidden (insufficient permissions) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Insufficient permissions value: success: false error: code: FORBIDDEN message: You do not have permission to access this resource meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unread method: POST '404': description: Not Found (resource not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conversation_not_found: summary: Conversation not found value: success: false error: code: NOT_FOUND message: Conversation not found meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unread method: POST '500': description: Internal Server Error (server error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: success: false error: code: INTERNAL_ERROR message: An internal server error occurred meta: timestamp: '2024-01-15T10:30:00Z' path: /api/v1/conversations/{conversation_id}/unread method: POST components: schemas: ErrorResponse: type: object required: - success - error - meta properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string example: VALIDATION_ERROR message: type: string example: Validation failed details: type: object additionalProperties: true nullable: true meta: type: object required: - timestamp - path - method properties: timestamp: type: string format: date-time example: '2024-01-15T10:30:00Z' path: type: string example: /public/api/v1/inboxes/{inbox_identifier}/contacts method: type: string example: POST contact: type: object properties: id: type: string format: uuid name: type: string email: type: string nullable: true phone_number: type: string nullable: true account_id: type: string format: uuid custom_attributes: type: object created_at: type: string format: date-time updated_at: type: string format: date-time conversation: type: object properties: id: type: string format: uuid display_id: type: string format: uuid status: type: string enum: - open - resolved - pending - snoozed contact_id: type: string format: uuid inbox_id: type: string format: uuid assignee_id: type: string format: uuid nullable: true team_id: type: string format: uuid nullable: true account_id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time last_activity_at: type: string format: date-time contact: $ref: '#/components/schemas/contact' assignee: $ref: '#/components/schemas/user' nullable: true inbox: type: object properties: id: type: string format: uuid channel_id: type: string format: uuid name: type: string channel_type: type: string enable_auto_assignment: type: boolean greeting_enabled: type: boolean greeting_message: type: string nullable: true working_hours_enabled: type: boolean out_of_office_message: type: string nullable: true timezone: type: string enable_email_collect: type: boolean csat_survey_enabled: type: boolean allow_messages_after_resolved: type: boolean auto_assignment_config: type: object additionalProperties: true lock_to_single_conversation: type: boolean csat_config: type: object additionalProperties: true sender_name_type: type: string business_name: type: string nullable: true display_name: type: string default_conversation_status: type: string nullable: true avatar_url: type: string working_hours: type: array items: type: object properties: day_of_week: type: integer closed_all_day: type: boolean open_hour: type: integer nullable: true open_minutes: type: integer nullable: true close_hour: type: integer nullable: true close_minutes: type: integer nullable: true open_all_day: type: boolean created_at: type: integer updated_at: type: integer provider: type: string user: type: object properties: id: type: string format: uuid name: type: string email: type: string avatar_url: type: string nullable: true available_name: type: string description: Display name for the user securitySchemes: userApiKey: type: apiKey in: header name: api_access_token ApiAccessToken: type: apiKey in: header name: api_access_token description: API access token for user authentication parameters: conversation_id: name: conversation_id in: path required: true description: Conversation ID (UUID) schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000