OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Conversations 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
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'
/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'
/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'
/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'
/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'
/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'
/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'
/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'
/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'
/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'
components:
schemas:
conversation_labels:
type: object
properties:
payload:
type: array
description: Array of labels
items:
type: string
conversation_list:
type: object
properties:
data:
type: object
properties:
meta:
type: object
properties:
mine_count:
type: number
unassigned_count:
type: number
assigned_count:
type: number
all_count:
type: number
payload:
type: array
description: array of conversations
items:
allOf:
- $ref: '#/components/schemas/generic_id'
- $ref: '#/components/schemas/conversation'
- type: object
properties:
meta:
type: object
properties:
sender:
type: object
properties:
additional_attributes:
type: object
description: The additional attributes of the sender
availability_status:
type: string
description: The availability status of the sender
email:
nullable: true
type: string
description: The email of the sender
id:
type: number
description: ID fo the sender
name:
type: string
description: The name of the sender
phone_number:
nullable: true
type: string
description: The phone number of the sender
blocked:
type: boolean
description: Whether the sender is blocked
identifier:
nullable: true
type: string
description: The identifier of the sender
thumbnail:
nullable: true
type: string
description: Avatar URL of the contact
custom_attributes:
type: object
description: The custom attributes of the sender
last_activity_at:
type: number
description: The last activity at of the sender
created_at:
type: number
description: The created at of the sender
channel:
type: string
description: Channel Type
assignee:
$ref: '#/components/schemas/user'
hmac_verified:
type: boolean
description: Whether the hmac is verified
bad_request_error:
title: data
type: object
properties:
description:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/request_error'
conversation_show:
type: object
allOf:
- $ref: '#/components/schemas/conversation'
- type: object
properties:
meta:
type: object
properties:
sender:
type: object
properties:
additional_attributes:
type: object
description: The additional attributes of the sender
availability_status:
type: string
description: The availability status of the sender
email:
nullable: true
type: string
description: The email of the sender
id:
type: number
description: ID fo the sender
name:
type: string
description: The name of the sender
phone_number:
nullable: true
type: string
description: The phone number of the sender
blocked:
type: boolean
description: Whether the sender is blocked
identifier:
nullable: true
type: string
description: The identifier of the sender
thumbnail:
nullable: true
type: string
description: Avatar URL of the contact
custom_attributes:
type: object
description: The custom attributes of the sender
last_activity_at:
type: number
description: The last activity at of the sender
created_at:
type: number
description: The created at of the sender
channel:
type: string
description: Channel Type
assignee:
$ref: '#/components/schemas/user'
hmac_verified:
type: boolean
description: Whether the hmac is verified
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
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
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:
nullable: true
type: string
message_signature:
nullable: true
type: string
email:
type: string
hmac_identifier:
type: string
inviter_id:
nullable: true
type: number
name:
type: string
provider:
type: string
pubsub_token:
type: string
role:
type: string
enum:
- agent
- administrator
ui_settings:
type: object
uid:
type: string
type:
nullable: true
type: string
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:
nullable: true
type: string
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:
nullable: true
type: number
custom_role:
nullable: true
type: object
message:
type: object
properties:
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-conversations-api-openapi.yml