openapi: 3.0.3
info:
  title: Chatwoot Account AgentBots Messages 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: Messages API
  description: Public message APIs
paths:
  /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages:
    parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    post:
      tags:
      - Messages API
      operationId: create-a-message
      summary: Create a message
      description: Create a message
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/public_message_create_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_message'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    get:
      tags:
      - Messages API
      operationId: list-all-conversation-messages
      summary: List all messages
      description: List all messages in the conversation
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: Array of messages
                items:
                  $ref: '#/components/schemas/public_message'
        '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}/messages/{message_id}
  : parameters:
    - $ref: '#/components/parameters/public_inbox_identifier'
    - $ref: '#/components/parameters/public_contact_identifier'
    - $ref: '#/components/parameters/conversation_id'
    - $ref: '#/components/parameters/message_id'
    patch:
      tags:
      - Messages API
      operationId: update-a-message
      summary: Update a message
      description: Update a message
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/public_message_update_payload'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_message'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
components:
  schemas:
    public_message_create_payload:
      type: object
      properties:
        content:
          type: string
          description: Content for the message
          example: Hello, how can I help you?
        echo_id:
          type: string
          description: Temporary identifier which will be passed back via websockets
          example: '1234567890'
    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_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
    public_message_update_payload:
      type: object
      properties:
        submitted_values:
          type: object
          description: Replies to the Bot Message Types
          properties:
            name:
              type: string
              description: The name of the submiitted value
              example: My Name
            title:
              type: string
              description: The title of the submitted value
              example: My Title
            value:
              type: string
              description: The value of the submitted value
              example: value
            csat_survey_response:
              type: object
              description: The CSAT survey response
              properties:
                feedback_message:
                  type: string
                  description: The feedback message of the CSAT survey response
                  example: Great service!
                rating:
                  type: integer
                  description: The rating of the CSAT survey response
                  example: 5
  parameters:
    conversation_id:
      in: path
      name: conversation_id
      schema:
        type: integer
      required: true
      description: The numeric ID of the conversation
    message_id:
      in: path
      name: message_id
      schema:
        type: integer
      required: true
      description: The numeric ID of the message
    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