openapi: 3.0.3 info: title: Chatwoot Account AgentBots Conversations API description: This is the API documentation for Chatwoot server. 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: Conversations description: Conversation management APIs paths: /api/v1/accounts/{account_id}/conversations/meta: parameters: - $ref: '#/components/parameters/account_id' get: tags: - Conversations 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: Success content: application/json: schema: type: object properties: meta: type: object properties: mine_count: type: number unassigned_count: type: number assigned_count: type: number all_count: type: number '400': description: Bad Request Error content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations: parameters: - $ref: '#/components/parameters/account_id' get: tags: - Conversations 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: Success content: application/json: schema: $ref: '#/components/schemas/conversation_list' '400': description: Bad Request Error content: application/json: schema: $ref: '#/components/schemas/bad_request_error' post: tags: - Conversations operationId: newConversation summary: Create New Conversation description: "Creating a conversation in chatwoot requires a source id. \n\n Learn more about source_id: https://www.chatwoot.com/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: Success content: application/json: schema: type: object properties: id: type: number description: ID of the conversation account_id: type: number description: Account Id inbox_id: type: number description: ID of the inbox '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/filter: parameters: - $ref: '#/components/parameters/account_id' post: tags: - Conversations 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: Success content: application/json: schema: $ref: '#/components/schemas/conversation_list' '400': description: Bad Request Error content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' get: tags: - Conversations 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: Success content: application/json: schema: $ref: '#/components/schemas/conversation_show' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' patch: tags: - Conversations 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 sla_policy_id: type: number description: The ID of the SLA policy (Available only in Enterprise edition) example: 1 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/conversation' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' post: tags: - Conversations operationId: toggle-status-of-a-conversation summary: Toggle Status description: 'Toggle the status of a conversation. Pass `status` to explicitly set the conversation state. Use `snoozed` along with `snoozed_until` to snooze a conversation until a specific time. If `snoozed_until` is omitted, the conversation is snoozed until the next reply from the contact. Regardless of the value provided, snoozed conversations always reopen on the next reply from the contact.' security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - open - resolved - pending - snoozed description: The status of the conversation example: open snoozed_until: type: number description: When status is `snoozed`, schedule the reopen time as a Unix timestamp in seconds. If not provided, the conversation is snoozed until the next customer reply. The conversation always reopens when the customer replies. example: 1757506877 responses: '200': description: Success content: application/json: schema: type: object properties: meta: type: object payload: type: object properties: success: type: boolean current_status: type: string enum: - open - resolved - pending - snoozed conversation_id: type: number '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_priority: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' post: tags: - Conversations 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: Success '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' post: tags: - Conversations operationId: toggle-typing-status-of-a-conversation summary: Toggle Typing Status description: Toggles the typing status for a conversation. security: - userApiKey: [] - agentBotApiKey: [] requestBody: required: true content: application/json: schema: type: object required: - typing_status properties: typing_status: type: string enum: - 'on' - 'off' description: Typing status to set. example: 'on' is_private: type: boolean description: Whether the typing event is for private notes. example: false responses: '200': description: Success '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' post: tags: - Conversations 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: Success content: application/json: schema: type: object properties: custom_attributes: type: object description: The custom attributes of the conversation '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' get: tags: - Conversations operationId: list-all-labels-of-a-conversation summary: List Labels security: - userApiKey: [] description: Lists all the labels of a conversation responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/conversation_labels' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' post: tags: - Conversations 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: Success content: application/json: schema: $ref: '#/components/schemas/conversation_labels' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v1/accounts/{account_id}/conversations/{conversation_id}/reporting_events: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/conversation_id' get: tags: - Conversations operationId: get-conversation-reporting-events summary: Conversation Reporting Events security: - userApiKey: [] description: Get reporting events for a specific conversation. This endpoint returns events such as first response time, resolution time, and other metrics for the conversation, sorted by creation time in ascending order. responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/reporting_event' description: Array of reporting events for the conversation '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' components: schemas: conversation_labels: type: object properties: payload: type: array description: Array of labels items: type: string conversation_list: type: object properties: data: type: object properties: meta: type: object properties: mine_count: type: number unassigned_count: type: number assigned_count: type: number all_count: type: number payload: type: array description: array of conversations items: allOf: - $ref: '#/components/schemas/generic_id' - $ref: '#/components/schemas/conversation' - type: object properties: meta: type: object properties: sender: type: object properties: additional_attributes: type: object description: The additional attributes of the sender availability_status: type: string description: The availability status of the sender email: nullable: true type: string description: The email of the sender id: type: number description: ID fo the sender name: type: string description: The name of the sender phone_number: nullable: true type: string description: The phone number of the sender blocked: type: boolean description: Whether the sender is blocked identifier: nullable: true type: string description: The identifier of the sender thumbnail: nullable: true type: string description: Avatar URL of the contact custom_attributes: type: object description: The custom attributes of the sender last_activity_at: type: number description: The last activity at of the sender created_at: type: number description: The created at of the sender channel: type: string description: Channel Type assignee: $ref: '#/components/schemas/user' hmac_verified: type: boolean description: Whether the hmac is verified bad_request_error: title: data type: object properties: description: type: string errors: type: array items: $ref: '#/components/schemas/request_error' conversation_show: type: object allOf: - $ref: '#/components/schemas/conversation' - type: object properties: meta: type: object properties: sender: type: object properties: additional_attributes: type: object description: The additional attributes of the sender availability_status: type: string description: The availability status of the sender email: nullable: true type: string description: The email of the sender id: type: number description: ID fo the sender name: type: string description: The name of the sender phone_number: nullable: true type: string description: The phone number of the sender blocked: type: boolean description: Whether the sender is blocked identifier: nullable: true type: string description: The identifier of the sender thumbnail: nullable: true type: string description: Avatar URL of the contact custom_attributes: type: object description: The custom attributes of the sender last_activity_at: type: number description: The last activity at of the sender created_at: type: number description: The created at of the sender channel: type: string description: Channel Type assignee: $ref: '#/components/schemas/user' hmac_verified: type: boolean description: Whether the hmac is verified request_error: type: object properties: field: type: string message: type: string code: type: string conversation_create_payload: type: object required: - source_id properties: source_id: type: string description: Conversation source id example: '1234567890' inbox_id: type: integer description: 'Id of inbox in which the conversation is created
Allowed Inbox Types: Website, Phone, Api, Email' example: 1 contact_id: type: integer description: Contact Id for which conversation is created example: 1 additional_attributes: type: object description: Lets you specify attributes like browser information example: browser: Chrome browser_version: 89.0.4389.82 os: Windows os_version: '10' custom_attributes: type: object description: The object to save custom attributes for conversation, accepts custom attributes key and value example: attribute_key: attribute_value priority_conversation_number: 3 status: type: string enum: - open - resolved - pending description: Specify the conversation whether it's pending, open, closed example: open assignee_id: type: integer description: Agent Id for assigning a conversation to an agent example: 1 team_id: type: integer description: Team Id for assigning a conversation to a team\ example: 1 snoozed_until: type: string format: date-time description: Snoozed until date time example: '2030-07-21T17:32:28Z' message: type: object description: The initial message to be sent to the conversation required: - content properties: content: type: string description: The content of the message example: Hello, how can I help you? template_params: type: object description: The template params for the message in case of whatsapp Channel properties: name: type: string description: Name of the template example: sample_issue_resolution category: type: string description: Category of the template example: UTILITY language: type: string description: Language of the template example: en_US processed_params: type: object description: The processed param values for template variables in template example: '1': Chatwoot generic_id: type: object properties: id: type: number user: type: object properties: id: type: number access_token: type: string account_id: type: number available_name: type: string avatar_url: type: string confirmed: type: boolean display_name: nullable: true type: string message_signature: nullable: true type: string email: type: string hmac_identifier: type: string inviter_id: nullable: true type: number name: type: string provider: type: string pubsub_token: type: string role: type: string enum: - agent - administrator ui_settings: type: object uid: type: string type: nullable: true type: string custom_attributes: type: object description: Available for users who are created through platform APIs and has custom attributes associated. accounts: type: array items: type: object properties: id: type: number name: type: string status: type: string active_at: nullable: true type: string format: date-time role: type: string enum: - administrator - agent permissions: type: array items: type: string availability: type: string availability_status: type: string auto_offline: type: boolean custom_role_id: nullable: true type: number custom_role: nullable: true type: object message: type: object properties: id: type: number description: The ID of the message content: type: string description: The text content of the message account_id: type: number description: The ID of the account inbox_id: type: number description: The ID of the inbox conversation_id: type: number description: The ID of the conversation message_type: type: integer enum: - 0 - 1 - 2 - 3 description: The type of the message created_at: type: integer description: The time at which message was created updated_at: type: integer description: The time at which message was updated private: type: boolean description: The flags which shows whether the message is private or not status: nullable: true type: string enum: - sent - delivered - read - failed - null description: The status of the message source_id: nullable: true type: string description: The source ID of the message content_type: nullable: true type: string enum: - text - input_text - input_textarea - input_email - input_select - cards - form - article - incoming_email - input_csat - integrations - sticker - voice_call - null description: The type of the template message content_attributes: type: object description: The content attributes for each content_type sender_type: nullable: true type: string enum: - Contact - User - AgentBot - Captain::Assistant - null description: The type of the sender sender_id: nullable: true type: number description: The ID of the sender external_source_ids: type: object description: The external source IDs of the message additional_attributes: type: object description: The additional attributes of the message processed_message_content: nullable: true type: string description: The processed message content sentiment: nullable: true type: object description: The sentiment of the message conversation: nullable: true type: object description: The conversation object attachment: nullable: true type: object description: The file object attached to the image sender: type: object description: User/Agent/AgentBot object conversation: type: object properties: id: type: number description: ID of the conversation messages: type: array items: $ref: '#/components/schemas/message' account_id: type: number description: Account Id uuid: type: string description: UUID of the conversation additional_attributes: type: object description: The object containing additional attributes related to the conversation agent_last_seen_at: type: number description: The last activity at of the agent assignee_last_seen_at: type: number description: The last activity at of the assignee can_reply: type: boolean description: Whether the conversation can be replied to contact_last_seen_at: type: number description: The last activity at of the contact custom_attributes: type: object description: The object to save custom attributes for conversation, accepts custom attributes key and value inbox_id: type: number description: ID of the inbox labels: type: array items: type: string description: The labels of the conversation muted: type: boolean description: Whether the conversation is muted snoozed_until: nullable: true type: number description: The time at which the conversation will be unmuted status: type: string enum: - open - resolved - pending description: The status of the conversation created_at: type: number description: The time at which conversation was created updated_at: type: number description: The time at which conversation was updated timestamp: type: number description: The time at which conversation was created first_reply_created_at: nullable: true type: number description: The time at which the first reply was created unread_count: type: number description: The number of unread messages last_non_activity_message: oneOf: - $ref: '#/components/schemas/message' - type: 'null' description: The last non activity message last_activity_at: type: number description: The last activity at of the conversation priority: nullable: true type: string description: The priority of the conversation waiting_since: nullable: true type: number description: The time at which the conversation was waiting sla_policy_id: nullable: true type: number description: The ID of the SLA policy applied_sla: type: object description: The applied SLA sla_events: type: array items: type: object description: SLA event objects reporting_event: type: object properties: id: type: number description: ID of the reporting event name: type: string description: Name of the event (e.g., first_response, resolution, reply_time) value: type: number format: double description: Value of the metric in seconds value_in_business_hours: type: number format: double description: Value of the metric in seconds, calculated only for business hours event_start_time: type: string format: date-time description: The timestamp when the event started event_end_time: type: string format: date-time description: The timestamp when the event ended account_id: type: number description: ID of the account conversation_id: nullable: true type: number description: ID of the conversation inbox_id: nullable: true type: number description: ID of the inbox user_id: nullable: true type: number description: ID of the user/agent created_at: type: string format: date-time description: The timestamp when the reporting event was created updated_at: type: string format: date-time description: The timestamp when the reporting event was last updated parameters: conversation_id: in: path name: conversation_id schema: type: integer required: true description: The numeric ID of the conversation account_id: in: path name: account_id schema: type: integer required: true description: The numeric ID of the account 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. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. agentBotApiKey: type: apiKey in: header name: api_access_token description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis. 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. x-tagGroups: - name: Platform tags: - Accounts - Account Users - AgentBots - Users - name: Application tags: - Account AgentBots - Account - Agents - Audit Logs - Canned Responses - Contacts - Contact Labels - Conversation Assignments - Conversation Labels - Conversations - Custom Attributes - Custom Filters - Inboxes - Integrations - Labels - Messages - Profile - Reports - Teams - Webhooks - Automation Rule - Help Center - name: Client tags: - Contacts API - Conversations API - Messages API - name: Others tags: - CSAT Survey Page