OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Help Center 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: Help Center
description: Knowledge base management
paths:
/api/v1/accounts/{account_id}/portals:
parameters:
- $ref: '#/components/parameters/account_id'
post:
tags:
- Help Center
operationId: add-new-portal-to-account
summary: Add a new portal
description: Add a new portal to account
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/portal_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portal'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
get:
tags:
- Help Center
operationId: get-portal
summary: List all portals in an account
parameters:
- $ref: '#/components/parameters/account_id'
description: Get details of portals in an Account
security:
- userApiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portal'
example:
payload:
- id: 4
color: '#1F93FF'
custom_domain: chatwoot.help
header_text: Handbook
homepage_link: https://www.chatwoot.com
name: Handbook
page_title: Handbook
slug: handbook
archived: false
account_id: 1
config:
allowed_locales:
- code: en
articles_count: 32
categories_count: 9
inbox:
id: 37
avatar_url: https://example.com/avatar.png
channel_id: 1
name: Chatwoot
channel_type: Channel::WebWidget
greeting_enabled: true
widget_color: '#1F93FF'
website_url: chatwoot.com
logo:
id: 19399916
portal_id: 4
file_type: image/png
account_id: 1
file_url: https://example.com/logo.png
blob_id: 21239614
filename: square.png
meta:
all_articles_count: 0
categories_count: 9
default_locale: en
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/portals/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/portal_id'
patch:
tags:
- Help Center
operationId: update-portal-to-account
summary: Update a portal
description: Update a portal to account
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/portal_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/portal_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portal_single'
example:
payload:
id: 123
archived: false
color: '#1F93FF'
config:
allowed_locales:
- code: en
articles_count: 32
categories_count: 9
custom_domain: chatwoot.help
header_text: Handbook
homepage_link: https://www.chatwoot.com
name: Handbook
slug: handbook
page_title: Handbook
account_id: 123
inbox:
id: 123
name: Chatwoot
website_url: chatwoot.com
channel_type: Channel::WebWidget
avatar_url: https://example.com/avatar.png
widget_color: '#1F93FF'
website_token: 4cWzuf9i9jxN9tbnv8K9STKU
enable_auto_assignment: true
web_widget_script: <script>...</script>
welcome_title: Hi there ! 🙌🏼
welcome_tagline: We make it simple to connect with us.
greeting_enabled: true
greeting_message: Hey there 👋, Thank you for reaching out to us.
channel_id: 123
working_hours_enabled: true
enable_email_collect: true
csat_survey_enabled: true
timezone: America/Los_Angeles
business_name: Chatwoot
hmac_mandatory: true
logo:
id: 123
portal_id: 123
file_type: image/png
account_id: 123
file_url: https://example.com/logo.png
blob_id: 123
filename: square.png
meta:
all_articles_count: 32
categories_count: 9
default_locale: en
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Portal not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/portals/{id}/categories:
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/portal_id'
post:
tags:
- Help Center
operationId: add-new-category-to-account
summary: Add a new category
description: Add a new category to portal
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/category_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/category'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/portals/{id}/articles:
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/portal_id'
post:
tags:
- Help Center
operationId: add-new-article-to-account
summary: Add a new article
description: Add a new article to portal
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/article_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/article'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
components:
schemas:
portal_meta:
type: object
properties:
all_articles_count:
type: integer
description: Total number of articles
archived_articles_count:
nullable: true
type: integer
description: Number of archived articles
published_count:
nullable: true
type: integer
description: Number of published articles
draft_articles_count:
nullable: true
type: integer
description: Number of draft articles
categories_count:
type: integer
description: Number of categories
default_locale:
type: string
description: Default locale for the portal
category:
type: object
properties:
id:
type: integer
description:
type: string
description: The text content.
locale:
type: string
name:
type: string
slug:
type: string
position:
type: integer
portal_id:
type: integer
account_id:
type: integer
associated_category_id:
type: integer
description: To associate similar categories to each other, e.g same category of product documentation in different languages
parent_category_id:
type: integer
description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category.
category_create_update_payload:
type: object
properties:
name:
type: string
description: The name of the category
example: Category Name
description:
type: string
description: A description for the category
example: Category description
position:
type: integer
description: Category position in the portal list to sort
example: 1
slug:
type: string
description: The category slug used in the URL
example: category-name
locale:
type: string
description: The locale of the category
example: en
icon:
type: string
description: The icon of the category as a string (emoji)
example: 📚
parent_category_id:
type: integer
description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category.
example: 1
associated_category_id:
type: integer
description: To associate similar categories to each other, e.g same category of product documentation in different languages
example: 2
article_create_update_payload:
type: object
properties:
title:
type: string
description: The title of the article
example: Article Title
slug:
type: string
description: The slug of the article
example: article-title
position:
type: integer
description: article position in category
example: 1
content:
type: string
description: The text content.
example: This is the content of the article
description:
type: string
description: The description of the article
example: This is the description of the article
category_id:
type: integer
description: The category id of the article
example: 1
author_id:
type: integer
description: The author agent id of the article
example: 1
associated_article_id:
type: integer
description: To associate similar articles to each other, e.g to provide the link for the reference.
example: 2
status:
type: integer
description: The status of the article. 0 for draft, 1 for published, 2 for archived
example: 1
locale:
type: string
description: The locale of the article
example: en
meta:
type: object
description: Use for search
example:
tags:
- article_name
title: article title
description: article description
portal_create_update_payload:
type: object
properties:
color:
type: string
description: Header color for help-center in hex format
example: '#FFFFFF'
custom_domain:
type: string
description: Custom domain to display help center.
example: chatwoot.help
header_text:
type: string
description: Help center header
example: Handbook
homepage_link:
type: string
description: link to main dashboard
example: https://www.chatwoot.com/
name:
type: string
description: Name for the portal
example: Handbook
page_title:
type: string
description: Page title for the portal
example: Handbook
slug:
type: string
description: Slug for the portal to display in link
example: handbook
archived:
type: boolean
description: Status to check if portal is live
example: false
config:
type: object
description: Configuration about supporting locales
example:
allowed_locales:
- en
- es
default_locale: en
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
article:
type: object
properties:
id:
type: integer
content:
type: string
description: The text content.
meta:
type: object
position:
type: integer
status:
type: integer
enum:
- draft
- published
- archived
title:
type: string
slug:
type: string
views:
type: integer
portal_id:
type: integer
account_id:
type: integer
author_id:
type: integer
category_id:
type: integer
folder_id:
type: integer
associated_article_id:
type: integer
description: To associate similar articles to each other, e.g to provide the link for the reference.
portal_logo:
type: object
properties:
id:
type: integer
description: ID of the logo file
portal_id:
type: integer
description: ID of the portal this logo belongs to
file_type:
type: string
description: MIME type of the file
account_id:
type: integer
description: ID of the account
file_url:
type: string
description: URL to access the logo file
blob_id:
type: integer
description: ID of the blob
filename:
type: string
description: Name of the file
portal_config:
type: object
description: Configuration settings for the portal
properties:
allowed_locales:
type: array
description: List of allowed locales for the portal
items:
type: object
properties:
code:
type: string
description: The language code
articles_count:
type: integer
description: Number of articles in this locale
categories_count:
type: integer
description: Number of categories in this locale
portal_item:
type: object
properties:
id:
type: integer
description: The ID of the portal
archived:
type: boolean
description: Whether the portal is archived
color:
type: string
description: The color code for the portal
config:
$ref: '#/components/schemas/portal_config'
custom_domain:
type: string
description: Custom domain for the portal
header_text:
type: string
description: The header text for the portal
homepage_link:
type: string
description: Homepage link for the portal
name:
type: string
description: Name of the portal
slug:
type: string
description: URL slug for the portal
page_title:
type: string
description: Page title for the portal
account_id:
type: integer
description: ID of the account the portal belongs to
inbox:
$ref: '#/components/schemas/inbox'
logo:
$ref: '#/components/schemas/portal_logo'
meta:
$ref: '#/components/schemas/portal_meta'
inbox:
type: object
properties:
id:
type: number
description: ID of the inbox
name:
type: string
description: The name of the inbox
website_url:
type: string
description: Website URL
channel_type:
type: string
description: The type of the inbox
avatar_url:
type: string
description: The avatar image of the inbox
widget_color:
type: string
description: Widget Color used for customization of the widget
website_token:
type: string
description: Website Token
enable_auto_assignment:
type: boolean
description: The flag which shows whether Auto Assignment is enabled or not
web_widget_script:
type: string
description: Script used to load the website widget
welcome_title:
nullable: true
type: string
description: Welcome title to be displayed on the widget
welcome_tagline:
nullable: true
type: string
description: Welcome tagline to be displayed on the widget
greeting_enabled:
type: boolean
description: The flag which shows whether greeting is enabled
greeting_message:
nullable: true
type: string
description: A greeting message when the user starts the conversation
channel_id:
type: number
description: ID of the channel this inbox belongs to
working_hours_enabled:
type: boolean
description: The flag which shows whether working hours feature is enabled
enable_email_collect:
type: boolean
description: The flag to enable collecting email from contacts
csat_survey_enabled:
type: boolean
description: The flag to enable CSAT survey
auto_assignment_config:
type: object
description: Configuration settings for auto assignment
out_of_office_message:
nullable: true
type: string
description: Message to show when agents are out of office
working_hours:
type: array
description: Configuration for working hours of the inbox
items:
type: object
properties:
day_of_week:
type: number
description: Day of the week (0-6, where 0 is Sunday)
closed_all_day:
type: boolean
description: Whether the inbox is closed for the entire day
open_hour:
nullable: true
type: number
description: Hour when inbox opens (0-23)
open_minutes:
nullable: true
type: number
description: Minutes of the hour when inbox opens (0-59)
close_hour:
nullable: true
type: number
description: Hour when inbox closes (0-23)
close_minutes:
nullable: true
type: number
description: Minutes of the hour when inbox closes (0-59)
open_all_day:
type: boolean
description: Whether the inbox is open for the entire day
timezone:
type: string
description: Timezone configuration for the inbox
callback_webhook_url:
nullable: true
type: string
description: Webhook URL for callbacks
allow_messages_after_resolved:
type: boolean
description: Whether to allow messages after a conversation is resolved
lock_to_single_conversation:
type: boolean
description: Whether to lock a contact to a single conversation
sender_name_type:
type: string
description: Type of sender name to display (e.g., friendly)
business_name:
nullable: true
type: string
description: Business name associated with the inbox
hmac_mandatory:
type: boolean
description: Whether HMAC verification is mandatory
selected_feature_flags:
nullable: true
type: array
description: Selected feature flags for the inbox
items:
type: string
reply_time:
type: string
description: Expected reply time
messaging_service_sid:
nullable: true
type: string
description: Messaging service SID for SMS providers
phone_number:
nullable: true
type: string
description: Phone number associated with the inbox
medium:
type: string
description: Medium of communication (e.g., sms, email)
provider:
nullable: true
type: string
description: Provider of the channel
portal:
type: object
properties:
payload:
type: array
items:
$ref: '#/components/schemas/portal_item'
portal_single:
type: object
properties:
payload:
$ref: '#/components/schemas/portal_item'
parameters:
portal_id:
in: path
name: id
schema:
type: string
required: true
description: The slug identifier of the portal
account_id:
in: path
name: account_id
schema:
type: integer
required: true
description: The numeric ID of the account
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