Chatwoot Conversations API

openapi: 3.2.0
info:
  title: Chatwoot Conversations API
  termsOfService: https://www.chatwoot.com/terms-of-service/
  version: '1.0'
  description: 'Operations tagged Conversations across 2 of this provider''s published API definitions: chatwoot-application-api-openapi.yml, chatwoot-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.chatwoot.com/
- url: https://app.chatwoot.com
  description: Chatwoot Cloud. For self-hosted installations, substitute your own host.
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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /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'
    servers:
    - url: https://app.chatwoot.com/
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    - $ref: '#/components/parameters/ConversationId'
    post:
      operationId: assignConversation
      tags:
      - Conversations
      summary: Assign a conversation to an agent or a team.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                assignee_id:
                  type: integer
                team_id:
                  type: integer
      responses:
        '200':
          description: The assignment result.
      security:
      - userApiKey: []
    servers:
    - url: https://app.chatwoot.com
      description: Chatwoot Cloud. For self-hosted installations, substitute your own host.
components:
  schemas:
    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:
          type:
          - string
          - 'null'
        message_signature:
          type:
          - string
          - 'null'
        email:
          type: string
        hmac_identifier:
          type: string
        inviter_id:
          type:
          - number
          - 'null'
        name:
          type: string
        provider:
          type: string
        pubsub_token:
          type: string
        role:
          type: string
          enum:
          - agent
          - administrator
        ui_settings:
          type: object
        uid:
          type: string
        type:
          type:
          - string
          - 'null'
        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:
                type:
                - string
                - 'null'
                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:
                type:
                - number
                - 'null'
              custom_role:
                type:
                - object
                - 'null'
    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:
          type:
          - number
          - 'null'
          description: ID of the conversation
        inbox_id:
          type:
          - number
          - 'null'
          description: ID of the inbox
        user_id:
          type:
          - number
          - 'null'
          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
    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 <br/> 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
    request_error:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
        code:
          type: string
    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:
          type:
          - number
          - 'null'
          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:
          type:
          - number
          - 'null'
          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:
          type:
          - string
          - 'null'
          description: The priority of the conversation
        waiting_since:
          type:
          - number
          - 'null'
          description: The time at which the conversation was waiting
        sla_policy_id:
          type:
 

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-conversations-api-openapi.yml