OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Contacts API API
description: This is the API documentation for Chatwoot server.
version: 1.1.0
termsOfService: https://www.chatwoot.com/terms-of-service/
contact:
email: hello@chatwoot.com
license:
name: MIT License
url: https://opensource.org/licenses/MIT
servers:
- url: https://app.chatwoot.com/
tags:
- name: Contacts API
description: Public contact APIs
paths:
/public/api/v1/inboxes/{inbox_identifier}/contacts:
parameters:
- $ref: '#/components/parameters/public_inbox_identifier'
post:
tags:
- Contacts API
operationId: create-a-contact
summary: Create a contact
description: Create a contact
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/public_contact_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/public_contact'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}:
parameters:
- $ref: '#/components/parameters/public_inbox_identifier'
- $ref: '#/components/parameters/public_contact_identifier'
get:
tags:
- Contacts API
operationId: get-details-of-a-contact
summary: Get a contact
description: Get the details of a contact
security: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/public_contact'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The given contact does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
patch:
tags:
- Contacts API
operationId: update-a-contact
summary: Update a contact
description: Update a contact's attributes
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/public_contact_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/public_contact_record'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
components:
schemas:
public_contact_record:
type: object
additionalProperties: true
description: Full serialized contact record returned when the public API renders a Contact model directly.
properties:
id:
type: integer
description: Id of the contact
name:
nullable: true
type: string
description: Name of the contact when available
email:
nullable: true
type: string
description: Email of the contact
phone_number:
nullable: true
type: string
description: Phone number of the contact
identifier:
nullable: true
type: string
description: Identifier of the contact
blocked:
type: boolean
description: Whether the contact is blocked
additional_attributes:
nullable: true
type: object
description: Additional attributes of the contact when present
custom_attributes:
nullable: true
type: object
description: Custom attributes of the contact when present
contact_type:
nullable: true
type: string
description: Contact type of the contact when available
country_code:
nullable: true
type: string
description: Country code of the contact
last_activity_at:
nullable: true
type: string
description: Last activity timestamp of the contact in ISO 8601 format
created_at:
nullable: true
type: string
description: Created timestamp of the contact in ISO 8601 format
updated_at:
nullable: true
type: string
description: Updated timestamp of the contact in ISO 8601 format
last_name:
nullable: true
type: string
description: Last name of the contact
middle_name:
nullable: true
type: string
description: Middle name of the contact
location:
nullable: true
type: string
description: Location of the contact
account_id:
type: integer
description: Account id of the contact
company_id:
nullable: true
type: integer
description: Company id of the contact
label_list:
type: array
description: Labels applied to the contact
items:
type: string
bad_request_error:
title: data
type: object
properties:
description:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/request_error'
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
public_contact_create_update_payload:
type: object
properties:
identifier:
type: string
description: External identifier of the contact
example: '1234567890'
identifier_hash:
type: string
description: Identifier hash prepared for HMAC authentication
example: e93275d4eba0e5679ad55f5360af00444e2a888df9b0afa3e8b691c3173725f9
email:
type: string
description: Email of the contact
example: alice@acme.inc
name:
type: string
description: Name of the contact
example: Alice
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
custom_attributes:
type: object
description: Custom attributes of the customer
example: {}
public_contact:
type: object
properties:
id:
type: integer
description: Id of the contact
source_id:
type: string
description: The session identifier of the contact
name:
nullable: true
type: string
description: Name of the contact when available
email:
nullable: true
type: string
description: Email of the contact
phone_number:
nullable: true
type: string
description: Phone number of the contact
pubsub_token:
type: string
description: The token to be used to connect to chatwoot websocket
parameters:
public_contact_identifier:
in: path
name: contact_identifier
schema:
type: string
required: true
description: The source id of contact obtained on contact create
public_inbox_identifier:
in: path
name: inbox_identifier
schema:
type: string
required: true
description: The identifier obtained from API inbox channel
securitySchemes:
userApiKey:
type: apiKey
in: header
name: api_access_token
description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.
agentBotApiKey:
type: apiKey
in: header
name: api_access_token
description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis.
platformAppApiKey:
type: apiKey
in: header
name: api_access_token
description: This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles.
x-tagGroups:
- name: Platform
tags:
- Accounts
- Account Users
- AgentBots
- Users
- name: Application
tags:
- Account AgentBots
- Account
- Agents
- Audit Logs
- Canned Responses
- Contacts
- Contact Labels
- Conversation Assignments
- Conversation Labels
- Conversations
- Custom Attributes
- Custom Filters
- Inboxes
- Integrations
- Labels
- Messages
- Profile
- Reports
- Teams
- Webhooks
- Automation Rule
- Help Center
- name: Client
tags:
- Contacts API
- Conversations API
- Messages API
- name: Others
tags:
- CSAT Survey Page