OpenAPI Specification
openapi: 3.0.3
info:
title: Chatwoot Account AgentBots Teams 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: Teams
description: Team management APIs
paths:
/api/v1/accounts/{account_id}/teams:
parameters:
- $ref: '#/components/parameters/account_id'
get:
tags:
- Teams
operationId: list-all-teams
summary: List all teams
security:
- userApiKey: []
description: List all teams available in the current account
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: Array of teams
items:
$ref: '#/components/schemas/team'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
post:
tags:
- Teams
operationId: create-a-team
summary: Create a team
security:
- userApiKey: []
description: Create a team in the account
parameters:
- $ref: '#/components/parameters/account_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/team_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/team'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/teams/{team_id}:
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/team_id'
get:
tags:
- Teams
operationId: get-details-of-a-single-team
summary: Get a team details
security:
- userApiKey: []
description: Get the details of a team in the account
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/team'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The given team ID does not exist in the account
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
patch:
tags:
- Teams
operationId: update-a-team
summary: Update a team
security:
- userApiKey: []
description: Update a team's attributes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/team_create_update_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/team'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
delete:
tags:
- Teams
operationId: delete-a-team
summary: Delete a team
security:
- userApiKey: []
description: Delete a team from the account
responses:
'200':
description: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: The team does not exist in the account
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
/api/v1/accounts/{account_id}/teams/{team_id}/team_members:
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/team_id'
get:
tags:
- Teams
operationId: get-team-members
summary: List Agents in Team
description: Get Details of Agents in an Team
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/team_id'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: Array of all agents in the team
items:
$ref: '#/components/schemas/agent'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Team not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
post:
tags:
- Teams
operationId: add-new-agent-to-team
summary: Add a New Agent
description: Add a new Agent to Team
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_ids
properties:
user_ids:
type: array
items:
type: integer
description: IDs of users to be added to the team
example:
- 1
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: Array of all active agents
items:
$ref: '#/components/schemas/agent'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Team not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: User must exist
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
patch:
tags:
- Teams
operationId: update-agents-in-team
summary: Update Agents in Team
description: All agents except the one passed in params will be removed
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_ids
properties:
user_ids:
type: array
items:
type: integer
description: IDs of users to be added to the team
example:
- 1
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: Array of all agents in the team
items:
$ref: '#/components/schemas/agent'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Team not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: User must exist
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
delete:
tags:
- Teams
operationId: delete-agent-in-team
summary: Remove an Agent from Team
description: Remove an Agent from Team
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_ids
properties:
user_ids:
type: array
items:
type: integer
description: IDs of users to be deleted from the team
responses:
'200':
description: Success
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Team not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: User must exist
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'
team_create_update_payload:
type: object
properties:
name:
type: string
description: The name of the team
example: Support Team
description:
type: string
description: The description of the team
example: This is a team of support agents
allow_auto_assign:
type: boolean
description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team
example: true
team:
type: object
properties:
id:
type: number
description: The ID of the team
name:
type: string
description: The name of the team
description:
nullable: true
type: string
description: The description about the team
allow_auto_assign:
type: boolean
description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team
account_id:
type: number
description: The ID of the account with the team is a part of
is_member:
type: boolean
description: This field shows whether the current user is a part of the team
request_error:
type: object
properties:
field:
type: string
message:
type: string
code:
type: string
agent:
type: object
properties:
id:
type: integer
account_id:
type: integer
availability_status:
type: string
enum:
- online
- busy
- offline
readOnly: true
description: The effective availability status of the agent, derived from the configured availability, auto-offline setting, and current presence. To update an agent's configured availability, use the availability field in create or update requests.
auto_offline:
type: boolean
description: Whether the agent is automatically marked offline when they are away.
confirmed:
type: boolean
description: Whether the agent has confirmed their email address.
email:
type: string
description: The email of the agent
available_name:
type: string
description: The available name of the agent
name:
type: string
description: The name of the agent
role:
type: string
enum:
- agent
- administrator
description: The role of the agent
thumbnail:
type: string
description: The thumbnail of the agent
custom_role_id:
nullable: true
type: integer
description: The custom role id of the agent
parameters:
account_id:
in: path
name: account_id
schema:
type: integer
required: true
description: The numeric ID of the account
team_id:
in: path
name: team_id
schema:
type: integer
required: true
description: The ID of the team to be updated
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