OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Inboxes 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: 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'
/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'
/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'
/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'
/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'
/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'
components:
schemas:
agent_bot:
type: object
properties:
id:
type: number
description: ID of the agent bot
name:
type: string
description: The name of the agent bot
description:
type: string
description: The description about the agent bot
thumbnail:
type: string
description: The thumbnail of the agent bot
outgoing_url:
type: string
description: The webhook URL for the bot
bot_type:
type: string
description: The type of the bot
bot_config:
type: object
description: The configuration of the bot
account_id:
type: number
description: Account ID if it's an account specific bot
access_token:
type: string
description: The access token for the bot
system_bot:
type: boolean
description: Whether the bot is a system bot
bad_request_error:
title: data
type: object
properties:
description:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/request_error'
inbox_update_sms_channel_payload:
type: object
title: SMS channel settings
properties:
phone_number:
type: string
description: SMS phone number
example: '+15551234567'
provider_config:
type: object
description: Provider-specific SMS configuration
example:
api_key: your-api-key
api_secret: your-api-secret
application_id: your-application-id
account_id: your-account-id
inbox_create_telegram_channel_payload:
type: object
title: Telegram channel
required:
- type
- bot_token
properties:
type:
type: string
enum:
- telegram
example: telegram
bot_token:
type: string
description: Telegram bot token
example: 123456789:telegram-bot-token
inbox_create_api_channel_payload:
type: object
title: API channel
required:
- type
properties:
type:
type: string
enum:
- api
example: api
webhook_url:
type: string
description: Webhook URL for API channel inbox callbacks
example: https://example.com/webhook
hmac_mandatory:
type: boolean
description: Require HMAC verification for incoming API channel messages
example: false
additional_attributes:
type: object
description: Additional attributes stored on contacts created through the API channel
example:
source: mobile_app
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
inbox_update_whatsapp_channel_payload:
type: object
title: WhatsApp channel settings
properties:
phone_number:
type: string
description: WhatsApp phone number
example: '+15551234567'
provider:
type: string
description: WhatsApp provider. `default` is supported only for existing deprecated 360dialog setups.
enum:
- whatsapp_cloud
- default
example: whatsapp_cloud
provider_config:
type: object
description: WhatsApp provider configuration. Cloud channels use `api_key`, `phone_number_id`, and `business_account_id`; legacy 360dialog channels use `api_key`.
properties:
api_key:
type: string
description: Provider API key
example: your-api-key
phone_number_id:
type: string
description: Phone number ID for WhatsApp Cloud
example: your-phone-number-id
business_account_id:
type: string
description: Business account ID for WhatsApp Cloud
example: your-business-account-id
example:
api_key: your-api-key
phone_number_id: your-phone-number-id
business_account_id: your-business-account-id
inbox_create_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:
oneOf:
- $ref: '#/components/schemas/inbox_create_web_widget_channel_payload'
- $ref: '#/components/schemas/inbox_create_api_channel_payload'
- $ref: '#/components/schemas/inbox_create_email_channel_payload'
- $ref: '#/components/schemas/inbox_create_line_channel_payload'
- $ref: '#/components/schemas/inbox_create_telegram_channel_payload'
- $ref: '#/components/schemas/inbox_create_whatsapp_channel_payload'
- $ref: '#/components/schemas/inbox_create_sms_channel_payload'
discriminator:
propertyName: type
mapping:
web_widget: '#/components/schemas/inbox_create_web_widget_channel_payload'
api: '#/components/schemas/inbox_create_api_channel_payload'
email: '#/components/schemas/inbox_create_email_channel_payload'
line: '#/components/schemas/inbox_create_line_channel_payload'
telegram: '#/components/schemas/inbox_create_telegram_channel_payload'
whatsapp: '#/components/schemas/inbox_create_whatsapp_channel_payload'
sms: '#/components/schemas/inbox_create_sms_channel_payload'
inbox_update_line_channel_payload:
type: object
title: LINE channel settings
properties:
line_channel_id:
type: string
description: LINE channel ID
example: '1234567890'
line_channel_secret:
type: string
description: LINE channel secret
example: line-channel-secret
line_channel_token:
type: string
description: LINE channel access token
example: line-channel-token
inbox_create_email_channel_payload:
type: object
title: Email channel
required:
- type
- email
properties:
type:
type: string
enum:
- email
example: email
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-inboxes-api-openapi.yml