OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Contacts 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: Contacts
description: Contact management APIs
paths:
/api/v1/accounts/{account_id}/contacts:
get:
tags:
- Contacts
operationId: contactList
description: Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
summary: List Contacts
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/contact_sort_param'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
post:
tags:
- Contacts
operationId: contactCreate
description: Create a new Contact
summary: Create Contact
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/contact_create_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/extended_contact'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/contacts/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
get:
tags:
- Contacts
operationId: contactDetails
summary: Show Contact
security:
- userApiKey: []
description: Get a contact belonging to the account using ID
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_show_response'
'404':
description: Contact 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'
put:
tags:
- Contacts
operationId: contactUpdate
summary: Update Contact
security:
- userApiKey: []
description: Update a contact belonging to the account using ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/contact_update_payload'
responses:
'204':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_base'
'404':
description: Contact 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'
delete:
tags:
- Contacts
operationId: contactDelete
summary: Delete Contact
security:
- userApiKey: []
description: Delete a contact belonging to the account using ID
responses:
'200':
description: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/contacts/{id}/conversations:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
get:
tags:
- Contacts
operationId: contactConversations
summary: Contact Conversations
description: Get conversations associated with that contact
parameters:
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
security:
- userApiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_conversations_response'
'404':
description: Contact 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}/contacts/search:
get:
tags:
- Contacts
operationId: contactSearch
description: Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
summary: Search Contacts
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: q
in: query
schema:
type: string
description: Search using contact `name`, `identifier`, `email` or `phone number`
- $ref: '#/components/parameters/contact_sort_param'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/contacts/filter:
post:
tags:
- Contacts
operationId: contactFilter
description: Filter contacts with custom filter options and pagination
summary: Contact Filter
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- 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: name
filter_operator: equal_to
values:
- en
query_operator: AND
- attribute_key: country_code
filter_operator: equal_to
values:
- us
query_operator: null
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes:
post:
tags:
- Contacts
operationId: contactInboxCreation
description: Create a contact inbox record for an inbox
summary: Create contact inbox
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
schema:
type: number
description: ID of the contact
required: true
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inbox_id
properties:
inbox_id:
type: number
description: The ID of the inbox
example: 1
source_id:
type: string
description: Contact Inbox Source Id
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_inboxes'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: Incorrect payload
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes:
get:
tags:
- Contacts
operationId: contactableInboxesGet
description: Get List of contactable Inboxes
summary: Get Contactable Inboxes
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
schema:
type: number
description: ID of the contact
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contactable_inboxes_response'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: Incorrect payload
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/actions/contact_merge:
parameters:
- $ref: '#/components/parameters/account_id'
post:
tags:
- Contacts
operationId: contactMerge
summary: Merge Contacts
security:
- userApiKey: []
description: 'Merge two contacts into a single contact. The base contact remains and receives all
data from the mergee contact. After the merge, the mergee contact is permanently deleted.
This action is irreversible. All conversations, labels, and custom attributes from the
mergee contact will be moved to the base contact.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- base_contact_id
- mergee_contact_id
properties:
base_contact_id:
type: integer
description: ID of the contact that will remain after the merge and receive all data
example: 1
mergee_contact_id:
type: integer
description: ID of the contact that will be merged into the base contact and deleted
example: 2
responses:
'200':
description: Contacts merged successfully
content:
application/json:
schema:
$ref: '#/components/schemas/contact_base'
'400':
description: Bad request - invalid contact IDs or contacts cannot be merged
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: One or both contacts not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
components:
schemas:
bad_request_error:
title: data
type: object
properties:
description:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/request_error'
contact_inboxes:
type: object
properties:
source_id:
type: string
description: Contact Inbox Source Id
inbox:
$ref: '#/components/schemas/inbox_contact'
contact_inbox:
type: object
properties:
source_id:
type: string
description: Source identifier for the contact inbox
inbox:
type: object
properties:
id:
type: integer
description: ID of the inbox
avatar_url:
type: string
description: URL for the inbox avatar
channel_id:
type: integer
description: ID of the channel
name:
type: string
description: Name of the inbox
channel_type:
type: string
description: Type of channel
provider:
nullable: true
type: string
description: Provider of the inbox
extended_contact:
allOf:
- $ref: '#/components/schemas/contact'
- type: object
properties:
id:
type: number
description: Id of the user
availability_status:
type: string
enum:
- online
- offline
description: Availability status of the user
contacts_list_response:
type: object
properties:
meta:
$ref: '#/components/schemas/contact_meta'
payload:
type: array
items:
$ref: '#/components/schemas/contact_list_item'
description: List of contacts
inbox_contact:
type: object
properties:
id:
type: number
description: ID of the inbox
avatar_url:
type: string
description: The avatar image of the inbox
channel_id:
type: number
description: The ID of the channel
name:
type: string
description: The name of the inbox
channel_type:
type: string
description: The type of the inbox
provider:
type: string
description: The provider of the inbox
contact_base:
allOf:
- $ref: '#/components/schemas/generic_id'
- $ref: '#/components/schemas/contact'
contact_conversations_response:
type: object
properties:
payload:
type: array
items:
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
description: List of conversations for the contact
contact:
type: object
properties:
payload:
type: array
items:
type: object
properties:
additional_attributes:
type: object
description: The object containing additional attributes related to the contact
availability_status:
type: string
description: The availability status of the contact
email:
type: string
description: The email address of the contact
id:
type: integer
description: The ID of the contact
name:
type: string
description: The name of the contact
phone_number:
type: string
description: The phone number of the contact
blocked:
type: boolean
description: Whether the contact is blocked
identifier:
type: string
description: The identifier of the contact
thumbnail:
type: string
description: The thumbnail of the contact
custom_attributes:
type: object
description: The custom attributes of the contact
example:
attribute_key: attribute_value
signed_up_at: dd/mm/yyyy
last_activity_at:
type: integer
description: The last activity at of the contact
created_at:
type: integer
description: The created at of the contact
contact_inboxes:
type: array
items:
$ref: '#/components/schemas/contact_inboxes'
contactable_inboxes_response:
type: object
properties:
payload:
type: array
items:
$ref: '#/components/schemas/contact_inbox'
description: List of contactable inboxes for the contact
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
generic_id:
type: object
properties:
id:
type: number
contact_create_payload:
type: object
required:
- inbox_id
properties:
inbox_id:
type: number
description: ID of the inbox to which the contact belongs
example: 1
name:
type: string
description: name of the contact
example: Alice
email:
type: string
description: email of the contact
example: alice@acme.inc
blocked:
type: boolean
description: whether the contact is blocked or not
example: false
phone_number:
type: string
description: phone number of the contact
example: '+123456789'
avatar:
type: string
format: binary
description: Send the form data with the avatar image binary or use the avatar_url
avatar_url:
type: string
description: The url to a jpeg, png file for the contact avatar
example: https://example.com/avatar.png
identifier:
type: string
description: A unique identifier for the contact in external system
example: '1234567890'
additional_attributes:
type: object
description: An object where you can store additional attributes for contact. example {"type":"customer", "age":30}
example:
type: customer
age: 30
custom_attributes:
type: object
description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}, this should have a valid custom attribute definition.
example: {}
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:
id:
type: number
description: The ID of the message
content:
type: string
description: The text content of the message
account_id:
type: number
description: The ID of the account
inbox_id:
type: number
description: The ID of the inbox
conversation_id:
type: number
description: The ID of the conversation
message_type:
type: integer
enum:
- 0
- 1
- 2
- 3
description: The type of the message
created_at:
type: integer
description: The time at which message was created
updated_at:
type: integer
description: The time at which message was updated
private:
type: boolean
description: The flags which shows whether the message is private or not
status:
nullable: true
type: string
enum:
- sent
- delivered
- read
- failed
- null
description: The status of the message
source_id:
nullable: true
type: string
description: The source ID of the message
content_type:
nullable: true
type: string
enum:
- text
- input_text
- input_textarea
- input_email
- input_select
- cards
- form
- article
- incoming_email
- input_csat
- integrations
- sticker
- voice_call
- null
description: The type of the template message
content_attributes:
type: object
description: The content attributes for each content_type
sender_type:
nullable: true
type: string
enum:
- Contact
- User
- AgentBot
- Captain::Assistant
- null
description: The type of the sender
sender_id:
nullable: true
type: number
description: The ID of the sender
external_source_ids:
type: object
description: The external source IDs of the message
additional_attributes:
type: object
description: The additional attributes of the message
processed_message_content:
nullable: true
type: string
description: The processed message content
sentiment:
nullable: true
type: object
description: The sentiment of the message
conversation:
nullable: true
type: object
description: The conversation object
attachment:
nullable: true
type: object
description: The file object attached to the image
sender:
type: object
description: User/Agent/AgentBot object
contact_meta:
type: object
properties:
count:
type: integer
description: Total number of contacts
current_page:
type: string
description: Current page number
contact_show_response:
type: object
properties:
payload:
$ref: '#/components/schemas/contact_list_item'
contact_update_payload:
type: object
properties:
name:
type: string
description: name of the contact
example: Alice
email:
type: string
description: email of the contact
example: alice@acme.inc
blocked:
type: boolean
description: whether the contact is blocked or not
example: false
phone_number:
type: string
description: phone number of the contact
example: '+123456789'
avatar:
type: string
format: binary
description: Send the form data with the avatar image binary or use the avatar_url
avatar_url:
type: string
description: The url to a jpeg, png file for the contact avatar
example: https://example.com/avatar.png
identifier:
type: string
description: A unique identifier for the contact in external system
example: '1234567890'
additional_attributes:
type: object
description: An object where you can store additional attributes for contact. example {"type":"customer", "age":30}
example:
type: customer
age: 30
custom_attributes:
type: object
description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}, this should have a valid custom attribute definition.
example: {}
contact_list_item:
type: object
properties:
additional_attributes:
type: object
description: The object containing additional attributes related to the contact
properties:
city:
type: string
description: City of the contact
country:
type: string
description: Country of the contact
country_code:
nullable: true
type: string
description: Country code of the contact
created_at_ip:
type: string
description: IP address when the contact was created
availability_status:
type: string
description: Availability status of the contact
enum:
- online
- offline
email:
nullable: true
type: string
description: The email address of the contact
id:
type: integer
description: The ID of the contact
name:
type: string
description: The name of the contact
phone_number:
nullable: true
type: string
description: The phone number of the contact
blocked:
type: boolean
description: Whether the contact is blocked
identifier:
nullable: true
type: string
description: The identifier of the contact
thumbnail:
type: string
description: The thumbnail of the contact
custom_attributes:
type: object
description: The custom attributes of the contact
last_activity_at:
nullable: true
type: integer
description: Timestamp of last activity
created_at:
type: integer
description: Timestamp when contact was created
contact_inboxes:
type: array
description: List of inboxes associated with this contact
items:
$ref: '#/components/schemas/contact_inbox'
conversati
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-contacts-api-openapi.yml