Chatwoot Inboxes API

openapi: 3.2.0
info:
  title: Chatwoot Inboxes API
  termsOfService: https://www.chatwoot.com/terms-of-service/
  version: '1.0'
  description: 'Operations tagged Inboxes 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: Inboxes
  description: Communication channels setup
paths:
  /api/v1/accounts/{account_id}/inboxes:
    get:
      tags:
      - Inboxes
      operationId: listAllInboxes
      summary: List all inboxes
      description: List all inboxes available in the current account
      security:
      - userApiKey: []
      parameters:
      - $ref: '#/components/parameters/account_id'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    description: Array of inboxes
                    items:
                      $ref: '#/components/schemas/inbox'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    post:
      tags:
      - Inboxes
      operationId: inboxCreation
      summary: Create an inbox
      description: You can create more than one website inbox in each account
      security:
      - userApiKey: []
      parameters:
      - $ref: '#/components/parameters/account_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inbox_create_payload'
            examples:
              web_widget:
                summary: Website inbox
                value:
                  name: Support
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_email_collect: true
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  allow_messages_after_resolved: true
                  channel:
                    type: web_widget
                    website_url: https://example.com
                    welcome_title: Welcome to our support
                    welcome_tagline: We are here to help you
                    widget_color: '#FF5733'
                    reply_time: in_a_few_minutes
                    pre_chat_form_enabled: false
                    continuity_via_email: true
                    hmac_mandatory: false
                    selected_feature_flags:
                    - attachments
                    - emoji_picker
                    - end_conversation
              api:
                summary: API channel
                value:
                  name: API Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: api
                    webhook_url: https://example.com/webhook
                    hmac_mandatory: false
                    additional_attributes:
                      source: mobile_app
              email:
                summary: Email channel
                value:
                  name: Email Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: email
                    email: support@example.com
                    imap_enabled: false
                    smtp_enabled: false
              line:
                summary: LINE channel
                value:
                  name: LINE Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: line
                    line_channel_id: '1234567890'
                    line_channel_secret: line-channel-secret
                    line_channel_token: line-channel-token
              telegram:
                summary: Telegram channel
                value:
                  name: Telegram Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: telegram
                    bot_token: 123456789:telegram-bot-token
              whatsapp:
                summary: WhatsApp channel
                value:
                  name: WhatsApp Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: whatsapp
                    phone_number: '+15551234567'
                    provider: whatsapp_cloud
                    provider_config:
                      api_key: your-api-key
                      phone_number_id: your-phone-number-id
                      business_account_id: your-business-account-id
              sms:
                summary: SMS channel
                value:
                  name: SMS Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    type: sms
                    phone_number: '+15551234567'
                    provider_config:
                      api_key: your-api-key
                      api_secret: your-api-secret
                      application_id: your-application-id
                      account_id: your-account-id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inbox'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    parameters:
    - $ref: '#/components/parameters/AccountId'
    servers:
    - url: https://app.chatwoot.com/
  /api/v1/accounts/{account_id}/inboxes/{id}:
    get:
      tags:
      - Inboxes
      operationId: GetInbox
      summary: Get an inbox
      security:
      - userApiKey: []
      description: Get an inbox available in the current account
      parameters:
      - $ref: '#/components/parameters/account_id'
      - name: id
        in: path
        schema:
          type: number
        description: ID of the inbox
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inbox'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    patch:
      tags:
      - Inboxes
      operationId: updateInbox
      summary: Update Inbox
      security:
      - userApiKey: []
      description: Update an existing inbox
      parameters:
      - $ref: '#/components/parameters/account_id'
      - name: id
        in: path
        schema:
          type: number
        description: ID of the inbox
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inbox_update_payload'
            examples:
              web_widget:
                summary: Website inbox settings
                value:
                  name: Support
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_email_collect: true
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  allow_messages_after_resolved: true
                  channel:
                    website_url: https://example.com
                    welcome_title: Welcome to our support
                    welcome_tagline: We are here to help you
                    widget_color: '#FF5733'
                    reply_time: in_a_few_minutes
                    pre_chat_form_enabled: false
                    continuity_via_email: true
                    hmac_mandatory: false
                    selected_feature_flags:
                    - attachments
                    - emoji_picker
                    - end_conversation
              api:
                summary: API channel settings
                value:
                  name: API Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    webhook_url: https://example.com/webhook
                    hmac_mandatory: false
                    additional_attributes:
                      source: mobile_app
              email:
                summary: Email channel settings
                value:
                  name: Email Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    email: support@example.com
                    imap_enabled: false
                    smtp_enabled: false
              line:
                summary: LINE channel settings
                value:
                  name: LINE Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    line_channel_id: '1234567890'
                    line_channel_secret: line-channel-secret
                    line_channel_token: line-channel-token
              telegram:
                summary: Telegram channel settings
                value:
                  name: Telegram Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    bot_token: 123456789:telegram-bot-token
              whatsapp:
                summary: WhatsApp channel settings
                value:
                  name: WhatsApp Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    phone_number: '+15551234567'
                    provider: whatsapp_cloud
                    provider_config:
                      api_key: your-api-key
                      phone_number_id: your-phone-number-id
                      business_account_id: your-business-account-id
              sms:
                summary: SMS channel settings
                value:
                  name: SMS Inbox
                  greeting_enabled: true
                  greeting_message: Hello, how can I help you?
                  enable_auto_assignment: true
                  working_hours_enabled: true
                  timezone: America/New_York
                  channel:
                    phone_number: '+15551234567'
                    provider_config:
                      api_key: your-api-key
                      api_secret: your-api-secret
                      application_id: your-application-id
                      account_id: your-account-id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inbox'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    parameters:
    - $ref: '#/components/parameters/AccountId'
    - name: id
      in: path
      required: true
      schema:
        type: integer
    delete:
      operationId: deleteInbox
      tags:
      - Inboxes
      summary: Delete an inbox.
      responses:
        '200':
          description: Inbox deleted.
    servers:
    - url: https://app.chatwoot.com/
  /api/v1/accounts/{account_id}/inboxes/{id}/agent_bot:
    get:
      tags:
      - Inboxes
      operationId: getInboxAgentBot
      summary: Show Inbox Agent Bot
      description: See if an agent bot is associated to the Inbox
      security:
      - userApiKey: []
      parameters:
      - $ref: '#/components/parameters/account_id'
      - name: id
        in: path
        schema:
          type: number
        description: ID of the inbox
        required: true
      responses:
        '204':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agent_bot'
        '404':
          description: Inbox not found, Agent bot not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '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}/inboxes/{id}/set_agent_bot:
    post:
      tags:
      - Inboxes
      operationId: updateAgentBot
      summary: Add or remove agent bot
      security:
      - userApiKey: []
      description: To add an agent bot pass agent_bot id, to remove agent bot from an inbox pass null
      parameters:
      - $ref: '#/components/parameters/account_id'
      - name: id
        in: path
        schema:
          type: number
        description: ID of the inbox
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_bot
              properties:
                agent_bot:
                  type: number
                  description: Agent bot ID
                  example: 1
      responses:
        '204':
          description: Success
        '404':
          description: Inbox not found, Agent bot not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '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}/inbox_members/{inbox_id}:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/inbox_id'
    get:
      tags:
      - Inboxes
      operationId: get-inbox-members
      summary: List Agents in Inbox
      description: Get Details of Agents in an Inbox
      security:
      - userApiKey: []
      parameters:
      - $ref: '#/components/parameters/inbox_id'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    description: Array of all active agents
                    items:
                      $ref: '#/components/schemas/agent'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '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}/inbox_members:
    parameters:
    - $ref: '#/components/parameters/account_id'
    post:
      tags:
      - Inboxes
      operationId: add-new-agent-to-inbox
      summary: Add a New Agent
      description: Add a new Agent to Inbox
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - inbox_id
              - user_ids
              properties:
                inbox_id:
                  type: integer
                  description: The ID of the inbox
                  example: 1
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: IDs of users to be added to the inbox
                  example:
                  - 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    description: Array of all active agents
                    items:
                      $ref: '#/components/schemas/agent'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '422':
          description: User must exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    patch:
      tags:
      - Inboxes
      operationId: update-agents-in-inbox
      summary: Update Agents in Inbox
      description: All agents except the one passed in params will be removed
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - inbox_id
              - user_ids
              properties:
                inbox_id:
                  type: string
                  description: The ID of the inbox
                  example: 1
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: IDs of users to be added to the inbox
                  example:
                  - 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    description: Array of all active agents
                    items:
                      $ref: '#/components/schemas/agent'
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '422':
          description: User must exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    delete:
      tags:
      - Inboxes
      operationId: delete-agent-in-inbox
      summary: Remove an Agent from Inbox
      description: Remove an Agent from Inbox
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - inbox_id
              - user_ids
              properties:
                inbox_id:
                  type: string
                  description: The ID of the inbox
                user_ids:
                  type: array
                  items:
                    type: integer
                  description: IDs of users to be deleted from the inbox
      responses:
        '200':
          description: Success
        '404':
          description: Inbox not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '422':
          description: User must exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
    servers:
    - url: https://app.chatwoot.com/
components:
  schemas:
    inbox_update_payload:
      type: object
      properties:
        name:
          type: string
          description: The name of the inbox.
          example: Support
        avatar:
          type: string
          format: binary
          description: Image file for avatar.
        greeting_enabled:
          type: boolean
          description: Enable greeting message.
          example: true
        greeting_message:
          type: string
          description: Greeting message to send when greeting messages are enabled.
          example: Hello, how can I help you?
        enable_email_collect:
          type: boolean
          description: 'Enable email collection.


            Available for: `Website`

            '
          example: true
        csat_survey_enabled:
          type: boolean
          description: Enable CSAT survey.
          example: true
        csat_config:
          type: object
          description: CSAT survey configuration.
          properties:
            display_type:
              type: string
              description: Display style for the CSAT survey.
              enum:
              - emoji
              - star
              example: emoji
            message:
              type: string
              description: Message shown with the CSAT survey.
              example: Please rate your conversation
            button_text:
              type: string
              description: Text shown on the CSAT survey button.
              example: Please rate us
            language:
              type: string
              description: Language code for the CSAT survey.
              example: en
            survey_rules:
              type: object
              description: Rules that decide when to show the CSAT survey.
              properties:
                operator:
                  type: string
                  example: contains
                values:
                  type: array
                  items:
                    type: string
                  example:
                  - billing
        enable_auto_assignment:
          type: boolean
          description: Enable Auto Assignment.
          example: true
        working_hours_enabled:
          type: boolean
          description: Enable working hours.
          example: true
        out_of_office_message:
          type: string
          description: Out of office message to send outside working hours.
          example: We are currently out of office. Please leave a message and we will get back to you.
        timezone:
          type: string
          description: Timezone of the inbox.
          example: America/New_York
        allow_messages_after_resolved:
          type: boolean
          description: 'Allow messages after conversation is resolved.


            Available for: `Website`

            '
          example: true
        lock_to_single_conversation:
          type: boolean
          description: 'Lock contact messages to a single active conversation.


            Available for: `API` `LINE` `Telegram` `WhatsApp` `SMS`

            '
          example: true
        portal_id:
          type: integer
          description: Id of the help center portal to attach to the inbox.
          example: 1
        sender_name_type:
          type: string
          description: 'Sender name type for outbound email replies.


            Available for: `Website` `Email`

            '
          enum:
          - friendly
          - professional
          example: friendly
        business_name:
          type: string
          description: 'Business name for outbound email replies.


            Available for: `Website` `Email`

            '
          example: My Business
        channel:
          anyOf:
          - $ref: '#/components/schemas/inbox_update_web_widget_channel_payload'
          - $ref: '#/components/schemas/inbox_update_api_channel_payload'
          - $ref: '#/components/schemas/inbox_update_email_channel_payload'
          - $ref: '#/components/schemas/inbox_update_line_channel_payload'
          - $ref: '#/components/schemas/inbox_update_telegram_channel_payload'
          - $ref: '#/components/schemas/inbox_update_whatsapp_channel_payload'
          - $ref: '#/components/schemas/inbox_update_sms_channel_payload'
    inbox:
      type: object
      properties:
        id:
          type: number
          description: ID of the inbox
        name:
          type: string
          description: The name of the inbox
        website_url:
          type: string
          description: Website URL
        channel_type:
          type: string
          description: The type of the inbox
        avatar_url:
          type: string
          description: The avatar image of the inbox
        widget_color:
          type: string
          description: Widget Color used for customization of the widget
        website_token:
          type: string
          description: Website Token
        enable_auto_assignment:
          type: boolean
          description: The flag which shows whether Auto Assignment is enabled or not
        web_widget_script:
          type: string
          description: Script used to load the website widget
        welcome_title:
          type:
          - string
          - 'null'
          description: Welcome title to be displayed on the widget
        welcome_tagline:
          type:
          - string
          - 'null'
          description: Welcome tagline to be displayed on the widget
        greeting_enabled:
          type: boolean
          description: The flag which shows whether greeting is enabled
        greeting_message:
          type:
          - string
          - 'null'
          description: A greeting message when the user starts the conversation
        channel_id:
          type: number
          description: ID of the channel this inbox belongs to
        working_hours_enabled:
          type: boolean
          description: The flag which shows whether working hours feature is enabled
        enable_email_collect:
          type: boolean
          description: The flag to enable collecting email from contacts
        csat_survey_enabled:
          type: boolean
          description: The flag to enable CSAT survey
        auto_assignment_config:
          type: object
          description: Configuration settings for auto assignment
        out_of_office_message:
          type:
          - string
          - 'null'
          description: Message to show when agents are out of office
        working_hours:
          type: array
          description: Configuration for working hours of the inbox
          items:
            type: object
            properties:
              day_of_week:
                type: number
                description: Day of the week (0-6, where 0 is Sunday)
              closed_all_day:
                type: boolean
                description: Whether the inbox is closed for the entire day
              open_hour:
                type:
                - number
                - 'null'
                description: Hour when inbox opens (0-23)
              open_minutes:
                type:
                - number
                - 'null'
                description: Minutes of the hour when inbox opens (0-59)
              close_hour:
                type:
                - number
                - 'null'
                description: Hour when inbox closes (0-23)
              close_minutes:
                type:
                - number
                - 'null'
                description: Minutes of the hour when inbox closes (0-59)
              open_all_day:
                type: boolean
                description: Whether the inbox is open for the entire day
        timezone:
          type: string
          description: Timezone configuration for the inbox
        callback_webhook_url:
          type:
          - string
          - 'null'
          description: Webhook URL for callbacks
        allow_messages_after_resolved:
          type: boolean
          description: Whether to allow messages after a conversation is resolved
        lock_to_single_conversation:
          type: boolean
          description: Whether to lock a contact to a single conversation
        sender_name_type:
          type: string
          description: Type of sender name to display (e.g., friendly)
        business_name:
          type:
          - string
          - 'null'
          description: Business name associated with the inbox
        hmac_mandatory:
          type: boolean
          description: Whether HMAC verification is mandatory
        selected_feature_flags:
          type:
          - array
          - 'null'
          description: Selected feature flags for the inbox
          items:
            type: string
        reply_time:
          type: string
          description: Expected reply time
        messaging_service_sid:
          type:
          - string
          - 'null'
          description: Messaging service SID for SMS providers
        phone_number:
          type:
          - string
          - 'null'
          description: Phone number associated with the inbox
        medium:
          type: 

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