openapi: 3.0.3
info:
  title: Chatwoot Account AgentBots Conversations API 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 API
  description: Public conversation APIs
paths:
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    post:
      tags:
      - Conversations API
      operationId: create-a-conversation
      summary: Create a conversation
      description: Create a conversation
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/public_conversation_create_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_conversation'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    get:
      tags:
      - Conversations API
      operationId: list-all-contact-conversations
      summary: List all conversations
      description: List all conversations for the contact
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: Array of conversations
                items:
                  $ref: '#/components/schemas/public_conversation'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    get:
      tags:
      - Conversations API
      operationId: get-single-conversation
      summary: Get a single conversation
      description: Retrieves the details of a specific conversation
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_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'
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_status:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    post:
      tags:
      - Conversations API
      operationId: resolve-conversation
      summary: Resolve a conversation
      description: Marks a conversation as resolved
      security: []
      responses:
        '200':
          description: Conversation resolved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_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'
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_typing:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    post:
      tags:
      - Conversations API
      operationId: toggle-typing-status
      summary: Toggle typing status
      description: Toggles the typing status in a conversation
      security: []
      parameters:
      - name: typing_status
        in: query
        required: true
        schema:
          type: string
        description: Typing status, either 'on' or 'off'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                typing_status:
                  type: string
                  enum:
                  - 'on'
                  - 'off'
                  description: The typing status to set
                  example: 'on'
      responses:
        '200':
          description: Typing status toggled successfully
        '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'
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/update_last_seen:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    post:
      tags:
      - Conversations API
      operationId: update-last-seen
      summary: Update last seen
      description: Updates the last seen time of the contact in a conversation
      security: []
      responses:
        '200':
          description: Last seen updated successfully
        '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'
components:
  schemas:
    public_contact_record:
      type: object
      additionalProperties: true
      description: Full serialized contact record returned when the public API renders a Contact model directly.
      properties:
        id:
          type: integer
          description: Id of the contact
        name:
          nullable: true
          type: string
          description: Name of the contact when available
        email:
          nullable: true
          type: string
          description: Email of the contact
        phone_number:
          nullable: true
          type: string
          description: Phone number of the contact
        identifier:
          nullable: true
          type: string
          description: Identifier of the contact
        blocked:
          type: boolean
          description: Whether the contact is blocked
        additional_attributes:
          nullable: true
          type: object
          description: Additional attributes of the contact when present
        custom_attributes:
          nullable: true
          type: object
          description: Custom attributes of the contact when present
        contact_type:
          nullable: true
          type: string
          description: Contact type of the contact when available
        country_code:
          nullable: true
          type: string
          description: Country code of the contact
        last_activity_at:
          nullable: true
          type: string
          description: Last activity timestamp of the contact in ISO 8601 format
        created_at:
          nullable: true
          type: string
          description: Created timestamp of the contact in ISO 8601 format
        updated_at:
          nullable: true
          type: string
          description: Updated timestamp of the contact in ISO 8601 format
        last_name:
          nullable: true
          type: string
          description: Last name of the contact
        middle_name:
          nullable: true
          type: string
          description: Middle name of the contact
        location:
          nullable: true
          type: string
          description: Location of the contact
        account_id:
          type: integer
          description: Account id of the contact
        company_id:
          nullable: true
          type: integer
          description: Company id of the contact
        label_list:
          type: array
          description: Labels applied to the contact
          items:
            type: string
    bad_request_error:
      title: data
      type: object
      properties:
        description:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/request_error'
    request_error:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
        code:
          type: string
    public_message_attachment:
      type: object
      additionalProperties: true
      description: Attachment payload. Available fields vary by attachment file_type.
      properties:
        id:
          type: integer
          description: Id of the attachment
        message_id:
          type: integer
          description: Id of the parent message
        file_type:
          type: string
          enum:
          - image
          - audio
          - video
          - file
          - location
          - fallback
          - share
          - story_mention
          - contact
          - ig_reel
          - ig_post
          - ig_story
          - embed
          description: Type of the attached file
        account_id:
          type: integer
          description: Id of the account
        extension:
          nullable: true
          type: string
          description: File extension
        data_url:
          nullable: true
          type: string
          description: URL of the file. Can be null when an attachment variant has no external URL.
        thumb_url:
          type: string
          description: URL of the file thumbnail
        file_size:
          type: integer
          description: File size in bytes
        width:
          nullable: true
          type: integer
          description: Width of the attachment when available
        height:
          nullable: true
          type: integer
          description: Height of the attachment when available
        coordinates_lat:
          type: number
          description: Latitude for location attachments
        coordinates_long:
          type: number
          description: Longitude for location attachments
        fallback_title:
          nullable: true
          type: string
          description: Fallback title for location, fallback, and contact attachments when available
        meta:
          type: object
          description: Metadata for contact attachments
        transcribed_text:
          type: string
          description: Transcribed text for audio attachments
    public_conversation_create_payload:
      type: object
      properties:
        custom_attributes:
          type: object
          description: Custom attributes of the conversation
          example: {}
    public_conversation:
      type: object
      properties:
        id:
          type: integer
          description: Id of the conversation
        uuid:
          type: string
          description: UUID of the conversation
        inbox_id:
          type: integer
          description: The inbox id of the conversation
        contact_last_seen_at:
          type: integer
          description: Timestamp of when the contact last seen the conversation (Unix timestamp)
        status:
          type: string
          enum:
          - open
          - resolved
          - pending
          - snoozed
          description: The status of the conversation
        agent_last_seen_at:
          type: integer
          description: Timestamp of when the agent last seen the conversation (Unix timestamp)
        messages:
          type: array
          items:
            $ref: '#/components/schemas/public_message'
          description: Messages in the conversation
        contact:
          $ref: '#/components/schemas/public_contact_record'
    public_message:
      type: object
      properties:
        id:
          type: integer
          description: Id of the message
        content:
          nullable: true
          type: string
          description: Text content of the message. Can be null for attachment-only messages.
        message_type:
          type: integer
          description: 'Denotes the message type. Possible values: 0 (incoming), 1 (outgoing), 2 (activity), 3 (template)'
        content_type:
          type: string
          description: Content type of the message
        content_attributes:
          type: object
          description: Additional content attributes of the message
        created_at:
          type: integer
          description: Created at Unix timestamp of the message
        conversation_id:
          type: integer
          description: Display Id of the conversation the message belongs to
        attachments:
          type: array
          description: Attachments if any
          items:
            $ref: '#/components/schemas/public_message_attachment'
        sender:
          $ref: '#/components/schemas/public_message_sender'
    public_message_sender:
      type: object
      additionalProperties: true
      description: Polymorphic sender payload returned by push_event_data. Available fields vary by sender type.
      properties:
        id:
          type: integer
          description: Id of the sender
        name:
          nullable: true
          type: string
          description: Name of the sender when available
        avatar_url:
          type: string
          description: Avatar URL of the sender. Present for senders of type user, agent_bot, and captain_assistant. Not present for contact senders (use thumbnail instead).
        thumbnail:
          type: string
          description: Avatar/thumbnail URL of the sender. Contact senders use this field; user senders may also include it.
        type:
          type: string
          enum:
          - contact
          - user
          - agent_bot
          - captain_assistant
          description: Type of the sender
        available_name:
          nullable: true
          type: string
          description: Display name for user senders
        availability_status:
          nullable: true
          type: string
          description: Availability status for user senders
        email:
          nullable: true
          type: string
          description: Email of the sender when the sender is a contact
        phone_number:
          nullable: true
          type: string
          description: Phone number of the sender when the sender is a contact
        identifier:
          nullable: true
          type: string
          description: Identifier of the sender when the sender is a contact
        blocked:
          type: boolean
          description: Whether the sender is blocked when the sender is a contact
        additional_attributes:
          nullable: true
          type: object
          description: Additional attributes when the sender is a contact and available
        custom_attributes:
          nullable: true
          type: object
          description: Custom attributes when the sender is a contact and available
        description:
          nullable: true
          type: string
          description: Description when the sender is a captain assistant
        created_at:
          nullable: true
          type: string
          description: Created timestamp in ISO 8601 format when the sender is a captain assistant
  parameters:
    conversation_id:
      in: path
      name: conversation_id
      schema:
        type: integer
      required: true
      description: The numeric ID of the conversation
    public_contact_identifier:
      in: path
      name: contact_identifier
      schema:
        type: string
      required: true
      description: The source id of contact obtained on contact create
    public_inbox_identifier:
      in: path
      name: inbox_identifier
      schema:
        type: string
      required: true
      description: The identifier obtained from API inbox channel
  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