Bots are conversational assistants designed to automate repetitive tasks and manage simple user interactions. Their behavior is fully customizable through predefined Bot Handlers, which are activated by specific actions or through Webhooks that communicate with your own external server.
For more information about Bots, please refer to the Bots Help Documentation.
Bot Handlers
Types of Bot Handlers
| Handler | \nDescription | \n
|---|---|
| Menu Handler | \nAdds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu. | \n
| Message Handler | \nTriggered when the bot receives a message. | \n
| Welcome Handler | \nDefines the greeting message sent when a user subscribes to the bot. | \n
| Mention Handler | \nTriggered when the bot is @mentioned in a chat or channel. | \n
| Incoming Webhook Handler | \nAllows external services to post messages into the bot via outgoing webhooks. | \n
| Context Handler | \nManages multi-turn conversations, maintaining context across a user's interaction with the bot. | \n
What you can do with the Bots API?
With the Bots API, you can retrieve information about a specific bot, list all bots within your organization, manage configurations specific to handlers, trigger bot calls programmatically, manage subscribers, and much more.
Each bot has an execution_type that defines how its handlers run when a trigger event occurs. The Bots API allows developers to create two types of bots:
Deluge Bots (default)
Deluge bot executes handler logic using Zoho's Deluge scripting language, hosted entirely within the Zoho Cliq Developer platform, where no external server is required.
execution_type is not specified during bot creation, it defaults to deluge.Webhook Bots
A Webhook bot delegates all handler execution to your own external server. When a trigger event fires, Zoho Cliq sends an HTTP POST request to the execution_url you configure, and your server processes the event and returns a response.
execution_type to webhook during bot creation and provide the execution_url where event payloads should be sent.\n Threshold limit: 30 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
USER_ID to return chats that include that user as a participant.70027934 returns chats that include that user ID.
'
- name: muted
in: query
required: false
schema:
type: boolean
description: 'Set this parameter to true to retrieve the list of chats which are muted by the user.
'
- name: limit
in: query
required: false
schema:
type: integer
format: int64
maxLength: 100
description: 'The number of chats that has to be retrieved.1711929600000.
'
- name: modified_after
in: query
required: false
schema:
type: integer
format: int64
description: 'Gets the list of chats where the last message is sent after the mentioned time.
1711929600000.
'
- name: drafts
in: query
required: false
schema:
type: boolean
description: 'Set this parameter to true to retrieve the list of chats which have unsent messages (drafts).
'
- name: pinned
in: query
required: false
schema:
type: boolean
description: 'Set this parameter to true to retrieve the list of chats which are pinned by the user.
'
- name: closed
in: query
required: false
schema:
type: boolean
description: 'Set this parameter to true to retrieve the list of chats which are closed by the user.
'
- name: joined
in: query
required: false
schema:
type: boolean
description: 'Set this parameter to true to retrieve the list of chats which are joined by the user.
'
- name: chat_ids
in: query
required: false
schema:
type: string
description: 'Comma-separated list of chat IDs to filter the chats.CHAT_ID to return all threads under that chat.threads - Chats that are threads of a parent chat.channel - Channel conversations.bot - Conversations with bots.dm - Direct messages between users.muted - Chats that are muted by the user.\n Threshold limit: 30 requests per min
\n Number of API calls allowed within a minute.
\n
| Error Code | \nDescription | \n
|---|---|
| 121_deptmem_message | \nPermission to chat with department members is restricted by admin. | \n
| 121_orgmem_message | \nPermission to chat with organization members is restricted by admin. | \n
| chat_continue_nonorg_nonmutual_contact_failed | \nThe user is no longer part of your contacts or organization. | \n
| 121_extmem_message | \nPermission to chat with external users is restricted by admin. | \n
| chat_not_available_with_this_inactive_user_and_cannot_create_newchat | \nNo chat history with this inactive user; cannot create a new chat. | \n
| invalid_inputs | \nMissing or invalid fields (e.g. chat_type not provided or unsupported). | \n
| no_valid_users_available_to_create_chat | \nAll specified users are inactive or not in your contacts. | \n
| insufficient_members_to_create_group_chat | \nNot enough valid members to create a group chat (minimum 3 including creator). | \n
| chat_operation_failed | \nUnexpected server error while creating the chat. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
operation field in the request body:\nread_status_update- Manage the read status of multiple chats in a single request. This is particularly useful for keeping your chat list organized and up-to-date, especially when you have a large number of conversations.clear_unread - Clears the unread message count or status to zero for the specified chats. If a specified chat has no unread entries, it is silently skipped.\n Threshold limits: 60 requests per min
\n Number of API calls allowed within a minute.
\n Lock periods: 5 minutes
Wait time before consecutive API requests.
\n
Possible Error Codes - Mark Chats as Read (read_status_update)
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'operation' is missing. | \n
| param_missing | \nThe param 'read_status' is missing. | \n
| param_missing | \nThe param 'chats' is missing. | \n
| param_missing | \nThe param 'chat_id' is missing. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
Possible Error Codes - Clear Unread Count (clear_unread)
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'operation' is missing. | \n
| param_missing | \nOne or more required params are missing: operation or chat_ids. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| invalid.inputs.submitted | \nAn invalid value was passed (e.g. unrecognised chat_type or sort_by). | \n
| invalid.time.submitted | \nmodified_before or modified_after is not a valid timestamp, or modified_after is not earlier than modified_before. | \n
| invalid_access | \nThe user is not a member of the organisation. | \n
| chat_operation_failed | \nAn unexpected server-side error occurred. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
1711929600000) or ISO 8601 format (for example, 2024-04-01T00:00:00Z).modified_before and modified_after in a request for predictable filtering.
Note: When both modified_before and modified_after are provided, modified_after must be earlier than modified_before.
'
- name: modified_after
in: query
required: false
schema:
type: string
description: 'Search and return only chats last modified after this time.1711929600000) or ISO 8601 format (for example, 2024-04-01T00:00:00Z).modified_before and modified_after in a request for predictable filtering.
Note: When both modified_before and modified_after are provided, modified_after must be earlier than modified_before.
'
- name: recipient
in: query
required: false
schema:
type: string
description: 'Filter by recipient user ID. Returns chats where this user is a participant. For direct messages, this will be the other participant; for group chats, this can be any member.
'
- name: chat_type
in: query
required: false
schema:
type: string
description: 'Filter by chat type.
Allowed values:direct_message, group_chat, channel, thread. You can specify multiple types separated by commas (e.g. direct_message,group_chat) to include multiple chat types in the results.
'
- name: parent_chat_id
in: query
required: false
schema:
type: string
description: 'Restrict results to threads belonging to this parent chat. Only applicable when filtering for thread-type chats.
'
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- usage
- recent
default: recent
description: "Sort results by usage or recent activity.usage: Sort by usage frequency, with the most frequently accessed chats appearing first.recent: Sort by recent activity, with the most recently active chats appearing first. This is the default sorting method.\n Threshold limit: 60 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
https://cliq.zoho.com/api/v3/chats/{CHAT_ID}?fields=title,chat_type,participant_count,permissions
'
- name: include
in: query
required: false
schema:
type: string
description: "Comma-separated list of additional data to include in the response.last_message_info: Includes details of the last message in the chat, such as message ID, sender, timestamp, content preview, and message type.include=last_message_info to include it in the response.https://cliq.zoho.com/api/v3/chats/{CHAT_ID}?include=last_message_info\n"
responses:
'200':
description: The request was successfully completed.
content:
application/json:
examples:
get_chat:
summary: Chat details
value:
type: chat
data:
chat_id: '2890538000000012345'
name: Q2 Product Review - Design, Engineering & QA
chat_type: group_chat
participant_count: 5
created_time: '2025-06-15T10:30:00+05:30'
last_modified_time: '2025-06-15T10:30:00+05:30'
pinned: false
removed: false
creator:
id: '70027934'
name: Tim Harrison
unread_message_count: 3
get_chat_with_last_message_info:
summary: Chat details with last message info
value:
type: chat
data:
chat_id: '2890538000000012345'
name: Q2 Product Review - Design, Engineering & QA
chat_type: group_chat
participant_count: 5
created_time: '2025-06-15T10:30:00+05:30'
last_modified_time: '2025-06-15T10:30:00+05:30'
pinned: false
removed: false
creator:
id: '70027934'
name: Tim Harrison
unread_message_count: 3
last_message_info:
message_id: '1773813859592_51531973059'
sender: '70027934'
time: '2025-06-15T10:30:00+05:30'
content:
text: Let's sync up before the review.
type: text
schema:
type: object
properties:
type:
type: string
example: chat
data:
$ref: '#/components/schemas/v3-chat'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Chats.READ
tags:
- chats
put:
summary: Update chat title or history status
operationId: updateChatV3
description: "Modify a chat's title or history status. Only one operation can be performed per request.update_title: Updates the visible title of the chat. Pass the new title in the title field.update_history_status : Controls whether chat history is retained. Set history_status to enabled or disabled.\n Threshold limits:
\n update_title: 60 req/min
\n update_history_status: 60 req/min
\n Lock periods:
\n update_title: 10 min
\n update_history_status: 10 min\n
Possible Error Codes - Update Title (update_title)
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'operation' is missing. | \n
| param_missing | \nThe param 'title' is missing. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_title_empty | \nTitle cannot be empty. Please enter a valid title. | \n
| channel_title_update_not_supported | \nChannel title update is not supported through this API. | \n
| contact_rename_not_supported | \nRenaming contacts in one-to-one chats is not allowed when contact display name is not preferred. | \n
| chatlet_title_modification_not_allowed | \nYou do not have permission to modify the title of this chatlet. | \n
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_title_update_failed | \nFailed to update the chat title. Please try again. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
Possible Error Codes - Update History Status (update_history_status)
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'operation' is missing. | \n
| param_missing | \nThe param 'history_status' is missing. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
title field.history_status field set to either enabled or disabled.operation is update_title.operation is update_history_status.update_title.
content:
application/json:
examples:
update_title:
summary: Title updated successfully
value:
type: chat.title
data:
title: Quarterly Rewards
chat_id: '1424358626334691820'
update_history_status:
summary: History status updated successfully
value: 204 No response
schema:
type: object
properties:
type:
type: string
example: chat.title
data:
type: object
properties:
title:
type: string
example: qa_renamed_xwswhsyz
chat_id:
type: string
example: '1424358626334691820'
'204':
description: No Content - returned for update_history_status operation. No response body.
content:
application/json:
examples:
update_history_status:
summary: History status updated successfully
value: {}
schema:
$ref: '#/components/schemas/NoResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Chats.UPDATE
tags:
- chats
/chats/{CHAT_ID1}:
put:
summary: Update Chat Read or Unread Status
operationId: markChatAsUnreadV3
x-display-path: /chats/{CHAT_ID}
x-virtual-endpoint: true
x-virtual-operation: true
x-note: 'CHAT_ID1 is a documentation alias for CHAT_ID to differentiate the two PUT operations under the same endpoint. This is to display both operations in the API reference. In actual API calls, use /chats/{CHAT_ID} for both operations and specify the desired operation in the request body.
'
description: "Marks a single chat as read or unread for the calling user.mark_as_read: Marks the chat as read up to a specific message. Pass the last_message_id of the chat till to be read.mark_as_unread: Marks the chat as unread from a specific message. Pass the target message_id.\n Threshold limit: 60 requests per min
\n Number of API calls allowed within a minute.\n
| Error Code | \nDescription | \n
|---|---|
| invalid.inputs.submitted | \nInvalid inputs | \n
| chat_access_denied | \nCaller is not a participant of this chat | \n
| chat_operation_failed | \nUnexpected server error | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
CHAT_ID1 is a documentation alias for CHAT_ID, used to separate the \"Update Chat Read or Unread Status\" operation for better readability while sharing the same /chats/{CHAT_ID} endpoint.\n"
requestBody:
required: true
content:
application/json:
examples:
mark_as_read:
summary: Mark chat as read
value:
operation: mark_as_read
last_message_id: '1773813859592_51531973059'
mark_as_unread:
summary: Mark chat as unread
value:
operation: mark_as_unread
message_id: '1773813859592_51531973059'
schema:
type: object
required:
- operation
properties:
operation:
type: string
description: "The update operation to perform on the chat.last_message_id field.message_id field indicating the message from which to mark as unread.operation is mark_as_read.
'
message_id:
type: string
description: 'The message from which to start the unread marker. Required when operation is mark_as_unread.
'
responses:
'204':
description: No Content - operation completed successfully. No response body.
content:
application/json:
schema:
$ref: '#/components/schemas/NoResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Chats.UPDATE
- Cliq_Auth:
- ZohoCliq.Messages.UPDATE
tags:
- chats
/chats/{CHAT_ID2}:
put:
summary: Clear Local Chat History
operationId: clearChatMessagesV3
x-display-path: /chats/{CHAT_ID}
x-virtual-endpoint: true
x-virtual-operation: true
x-note: 'CHAT_ID2 is a documentation alias for CHAT_ID to differentiate the two PUT operations under the same endpoint. This is to display both operations in the API reference. In actual API calls, use /chats/{CHAT_ID} for both operations and specify the desired operation in the request body.
'
description: "Clears the local message history of a chat for the current user. The chat itself and all members remain intact; only the locally visible message history is cleared.\nOnly supported for direct messages and group chats.\n\n Threshold limit: 60 requests per min
\n Number of API calls allowed within a minute.
\n
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'operation' is missing. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_clear_local_history_not_supported | \nClear local history is only supported for direct messages and group chats. | \n
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_clear_local_history_failed | \nUnable to clear local history. Please retry. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
CHAT_ID2 is a documentation alias for CHAT_ID, used to separate the "Clear Local Chat History" operation for better readability while sharing the same /chats/{CHAT_ID} endpoint.
'
requestBody:
required: true
content:
application/json:
examples:
clear_local_history:
summary: Clear local chat history
value:
operation: clear_local_history
schema:
type: object
required:
- operation
properties:
operation:
type: string
description: The operation to perform. Must be set to clear_local_history to clear the local chat history.
enum:
- clear_local_history
responses:
'204':
description: No Content - local chat history cleared successfully. No response body.
content:
application/json:
schema:
$ref: '#/components/schemas/NoResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Chats.UPDATE
tags:
- chats
/chats/{CHAT_ID3}:
put:
summary: Close a chat
operationId: closeChatV3
x-display-path: /chats/{CHAT_ID}
x-virtual-endpoint: true
x-virtual-operation: true
x-note: 'CHAT_ID3 is a documentation alias for CHAT_ID to differentiate the two PUT operations under the same endpoint. This is to display both operations in the API reference. In actual API calls, use /chats/{CHAT_ID} for both operations and specify the desired operation in the request body.
'
description: "Closes a chat by removing it from the recent chats list of the user. The chat will still be accessible through search and other means, all members remain intact and only the visibility in recent chats is affected.\n\n Threshold limit: 60 requests per min
\n Number of API calls allowed within a minute.
\n
| Error Code | \nDescription | \n
|---|---|
| chat_access_denied | \nCaller is not a participant of this chat. | \n
| chat_operation_failed | \nUnexpected server error. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
CHAT_ID3 is a documentation alias for CHAT_ID, used to separate the "Close a chat" operation for better readability while sharing the same /chats/{CHAT_ID} endpoint.
'
requestBody:
required: true
content:
application/json:
examples:
close_chat:
summary: Close a chat
value:
operation: close_chat
schema:
type: object
required:
- operation
properties:
operation:
type: string
description: The operation to perform. Must be set to close_chat to remove the chat from recent chats.
enum:
- close_chat
responses:
'204':
description: No Content - chat removed from recent chats successfully. No response body.
content:
application/json:
schema:
$ref: '#/components/schemas/NoResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Chats.UPDATE
tags:
- chats
/chats/{CHAT_ID}/members:
get:
summary: Retrieve members of a chat
operationId: Retrieve members of a chat
description: "Use this API to retrieve the list of members participating in a channel or group chat.\nfields query parameter.\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| group_chat_participants_limit_exceeded | \nThe maximum number of participants for this chat has been reached. | \n
| one_to_one_chat_add_member_not_allowed | \nAdding members to a one-to-one chat is not allowed. | \n
| chat_with_other_org_disabled | \nAdding members from other organizations is disabled. | \n
| member_add_failed | \nAn unexpected error occurred while adding members. | \n
| service_unavailable | \nThe messaging service is temporarily unavailable. Please try again later. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| one_to_one_chat_delete_member_not_allowed | \nRemoving members from a one-to-one chat is not allowed. | \n
| member_delete_failed | \nAn unexpected error occurred while removing members. | \n
| service_unavailable | \nThe messaging service is temporarily unavailable. Please try again later. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n Threshold limit: 50 requests per min
\n Number of API calls allowed within a minute.
\n Lock period: 10 seconds
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| invalid_request | \nFork input payload is invalid or incomplete. | \n
| operation_failed | \nUnable to create forked chat due to an internal error. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n Threshold limit: 100 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 50 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| param_missing | \nThe param 'action' is missing. | \n
| invalid.inputs.submitted | \nIncorrect values submitted. | \n
| chat_access_denied | \nYou must be a participant in this chat to perform this action. | \n
| chat_operation_failed | \nUnable to perform the action. Please retry. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
CHAT_ID4 is a documentation alias for CHAT_ID, used to document the "Mentioning available users in a Channel" use case separately while sharing the same /chats/{CHAT_ID}/messages endpoint, since the path is unchanged and only the message content pattern differs.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: "The text content of the message to be sent.\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests.
\n
| Error Code | \nDescription | \n
|---|---|
| thread_chatid_invalid | \nThe thread chat ID given is not according to the format. | \n
| external_communication_not_supported | \nSorry, external communication is not supported as per the organization policy. | \n
| operation_failed | \nSorry, we couldn't process your request due to a technical error. Please try again later. | \n
When an error occurs, the API returns a JSON response in this format:
\n{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
55743307,55622727
'
example: 631830848,631830849
include_participants:
type: boolean
default: false
description: 'Whether to include all participants from the original chat in the forked chat. If set to true, the user_ids field will be ignored and all participants will be included.
'
example: false
title:
type: string
maxLength: 255
description: 'Title of the forked chat. Required when creating a forked chat.
'
example: Discussion on Q3 Marketing Strategy
v3-typing-activity-request:
type: object
required:
- action
properties:
action:
type: string
description: "The typing activity to send to the chat.typing: Indicates that the user is currently typing a message.text_entered: Indicates that the user has entered text but has not yet sent the message.text_cleared: Indicates that the user has cleared the entered text.direct_message: A one-to-one chat with another user.group_chat: A chat with multiple users, requires a title.direct_message chat type.group_chat chat type.group_chat chat type.operation field:\nread_status_update): Set operation to read_status_update, read_status to read, and provide a chats array with each chat's chat_id and last_message_id. Returns 200 OK.clear_unread): Set operation to clear_unread and provide a chat_ids array. Returns 204 No Content.read_status_update: Marks the specified chats as read up to the given last_message_id. Requires read_status and chats fields.clear_unread: Clears the unread message count or status to zero for the specified chats. Requires chat_ids field.read_status_update operation only.read - Marks the specified chats as read.
'
enum:
- read
chats:
type: array
description: 'List of chats to mark as read. Applicable for the read_status_update operation only.clear_unread operation only.