OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Messages 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: Messages API
description: Public message APIs
paths:
/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages:
parameters:
- $ref: '#/components/parameters/public_inbox_identifier'
- $ref: '#/components/parameters/public_contact_identifier'
- $ref: '#/components/parameters/conversation_id'
post:
tags:
- Messages API
operationId: create-a-message
summary: Create a message
description: Create a message
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/public_message_create_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/public_message'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
get:
tags:
- Messages API
operationId: list-all-conversation-messages
summary: List all messages
description: List all messages in the conversation
security: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: Array of messages
items:
$ref: '#/components/schemas/public_message'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
? /public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages/{message_id}
: parameters:
- $ref: '#/components/parameters/public_inbox_identifier'
- $ref: '#/components/parameters/public_contact_identifier'
- $ref: '#/components/parameters/conversation_id'
- $ref: '#/components/parameters/message_id'
patch:
tags:
- Messages API
operationId: update-a-message
summary: Update a message
description: Update a message
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/public_message_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/public_message'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
components:
schemas:
public_message_create_payload:
type: object
properties:
content:
type: string
description: Content for the message
example: Hello, how can I help you?
echo_id:
type: string
description: Temporary identifier which will be passed back via websockets
example: '1234567890'
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_message_attachment:
type: object
additionalProperties: true
description: Attachment payload. Available fields vary by attachment file_type.
properties:
id:
type: integer
description: Id of the attachment
message_id:
type: integer
description: Id of the parent message
file_type:
type: string
enum:
- image
- audio
- video
- file
- location
- fallback
- share
- story_mention
- contact
- ig_reel
- ig_post
- ig_story
- embed
description: Type of the attached file
account_id:
type: integer
description: Id of the account
extension:
nullable: true
type: string
description: File extension
data_url:
nullable: true
type: string
description: URL of the file. Can be null when an attachment variant has no external URL.
thumb_url:
type: string
description: URL of the file thumbnail
file_size:
type: integer
description: File size in bytes
width:
nullable: true
type: integer
description: Width of the attachment when available
height:
nullable: true
type: integer
description: Height of the attachment when available
coordinates_lat:
type: number
description: Latitude for location attachments
coordinates_long:
type: number
description: Longitude for location attachments
fallback_title:
nullable: true
type: string
description: Fallback title for location, fallback, and contact attachments when available
meta:
type: object
description: Metadata for contact attachments
transcribed_text:
type: string
description: Transcribed text for audio attachments
public_message:
type: object
properties:
id:
type: integer
description: Id of the message
content:
nullable: true
type: string
description: Text content of the message. Can be null for attachment-only messages.
message_type:
type: integer
description: 'Denotes the message type. Possible values: 0 (incoming), 1 (outgoing), 2 (activity), 3 (template)'
content_type:
type: string
description: Content type of the message
content_attributes:
type: object
description: Additional content attributes of the message
created_at:
type: integer
description: Created at Unix timestamp of the message
conversation_id:
type: integer
description: Display Id of the conversation the message belongs to
attachments:
type: array
description: Attachments if any
items:
$ref: '#/components/schemas/public_message_attachment'
sender:
$ref: '#/components/schemas/public_message_sender'
public_message_sender:
type: object
additionalProperties: true
description: Polymorphic sender payload returned by push_event_data. Available fields vary by sender type.
properties:
id:
type: integer
description: Id of the sender
name:
nullable: true
type: string
description: Name of the sender when available
avatar_url:
type: string
description: Avatar URL of the sender. Present for senders of type user, agent_bot, and captain_assistant. Not present for contact senders (use thumbnail instead).
thumbnail:
type: string
description: Avatar/thumbnail URL of the sender. Contact senders use this field; user senders may also include it.
type:
type: string
enum:
- contact
- user
- agent_bot
- captain_assistant
description: Type of the sender
available_name:
nullable: true
type: string
description: Display name for user senders
availability_status:
nullable: true
type: string
description: Availability status for user senders
email:
nullable: true
type: string
description: Email of the sender when the sender is a contact
phone_number:
nullable: true
type: string
description: Phone number of the sender when the sender is a contact
identifier:
nullable: true
type: string
description: Identifier of the sender when the sender is a contact
blocked:
type: boolean
description: Whether the sender is blocked when the sender is a contact
additional_attributes:
nullable: true
type: object
description: Additional attributes when the sender is a contact and available
custom_attributes:
nullable: true
type: object
description: Custom attributes when the sender is a contact and available
description:
nullable: true
type: string
description: Description when the sender is a captain assistant
created_at:
nullable: true
type: string
description: Created timestamp in ISO 8601 format when the sender is a captain assistant
public_message_update_payload:
type: object
properties:
submitted_values:
type: object
description: Replies to the Bot Message Types
properties:
name:
type: string
description: The name of the submiitted value
example: My Name
title:
type: string
description: The title of the submitted value
example: My Title
value:
type: string
description: The value of the submitted value
example: value
csat_survey_response:
type: object
description: The CSAT survey response
properties:
feedback_message:
type: string
description: The feedback message of the CSAT survey response
example: Great service!
rating:
type: integer
description: The rating of the CSAT survey response
example: 5
parameters:
conversation_id:
in: path
name: conversation_id
schema:
type: integer
required: true
description: The numeric ID of the conversation
message_id:
in: path
name: message_id
schema:
type: integer
required: true
description: The numeric ID of the message
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