OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Labels 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: Labels
description: Account label management APIs
paths:
/api/v1/accounts/{account_id}/labels:
parameters:
- $ref: '#/components/parameters/account_id'
get:
tags:
- Labels
operationId: list-all-labels
summary: List all labels
security:
- userApiKey: []
description: List all labels available in the current account
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
payload:
type: array
description: Array of labels
items:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
post:
tags:
- Labels
operationId: create-a-label
summary: Create a label
security:
- userApiKey: []
description: Create a label in the account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/label_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/labels/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the label
get:
tags:
- Labels
operationId: get-details-of-a-single-label
summary: Get a label
security:
- userApiKey: []
description: Get the details of a label in the account
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The given label ID does not exist in the account
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
patch:
tags:
- Labels
operationId: update-a-label
summary: Update a label
security:
- userApiKey: []
description: Update a label's attributes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/label_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/label'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
delete:
tags:
- Labels
operationId: delete-a-label
summary: Delete a label
security:
- userApiKey: []
description: Delete a label from the account
responses:
'200':
description: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The label does not exist in the account
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'
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
label:
type: object
properties:
id:
type: number
description: The ID of the label
title:
type: string
description: The title of the label
description:
type: string
description: The description of the label
color:
type: string
description: Hex color code for the label
show_on_sidebar:
type: boolean
description: Whether the label should appear in the sidebar
label_create_update_payload:
type: object
properties:
title:
type: string
description: The label title
example: support
description:
type: string
description: A short description for the label
example: Conversations that need support follow-up
color:
type: string
description: Hex color code for the label
example: '#1f93ff'
show_on_sidebar:
type: boolean
description: Whether the label should appear in the sidebar
example: true
parameters:
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