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 Create a new Message Action. Message actions appear in the right-click / long-press context menu for individual chat messages. When a user selects the action, the configured handler executes with the selected message as input.\n
\n\n Message Actions support two execution types:\n
\nexecution_url with the event payload. Your server processes it and returns the response. Supports all 5 permissions (attachments, chat, location, message, user).\n Pass execution_type: \"webhook\" and a valid execution_url to create a Webhook message action. If execution_type is omitted, it defaults to deluge.\n
\n Threshold limit: 30 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| msgaction_creation_limit_exceeded | \nOrganization has reached the maximum number of message actions. | \n
| msgaction_name_already_exists | \nA message action with this name already exists. | \n
| invalid_inputs | \nRequest body validation failed. | \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: 30 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
sync_token value from the previous response. For the initial request, omit this parameter or set it to null to retrieve all message actions.
'
required: false
- schema:
description: ''
type: integer
in: query
name: limit
description: 'Maximum number of message actions to return per page.next_token, use its value in this parameter to retrieve the next page. Omit this parameter or set it to null if there are no more pages to fetch.
'
required: false
responses:
'200':
description: List of message actions returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageActionListItemsResponse'
example:
url: /api/v3/messageactions
type: messageaction
sync_token: NTB8MTc3NzQzMjI3NjY1OHw1MzcxOTAwMDAwMjEyNDAxMA==
data:
- multi_selectable: true
name: Create Ticket
id: '53719000002124010'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Create a helpdesk ticket
status: enabled
type: custom
message_types:
- text
- link
scope: organization
- multi_selectable: false
name: Translate
id: '53719000002124013'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Translate selected message to English
status: enabled
type: custom
message_types:
- text
scope: personal
'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.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'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.MessageActions.READ
tags:
- messageactions
/messageactions/{MESSAGE_ACTION_ID}:
patch:
summary: Update an existing message action
operationId: update_an_existing_message_act
description: "Update the configuration of an existing message action.\n\n All fields are optional. Only the fields you provide will be updated; omitted fields remain unchanged.\n
\n\n For Webhook message actions, you can update the execution_url independently at any time to redirect the action to a new server endpoint.\n
\n Threshold limit: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| msgaction_not_found | \nMessage action with the specified ID was not found. | \n
| msgaction_name_already_exists | \nAnother message action with this name already exists. | \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: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| msgaction_not_found | \nMessage action with the specified ID was not found. | \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: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| msgaction_not_found | \nMessage action with the specified ID was not found. | \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.
script attribute with the revised Deluge source code to execute when the action fires.permissions array to change which data attributes are forwarded to your server. All 5 permissions are available for message action handlers.\n Threshold limit: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| execution_handler_update_failed | \nFailed to update the execution handler. | \n
| execution_handler_not_found | \nSpecified handler was not found for this message action. | \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.
execution_handler, which is triggered when the message action is invoked.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: MESSAGE_ACTION_ID
in: path
name: MESSAGE_ACTION_ID
description: Unique numeric identifier of the message action. To learn how to retrieve this ID, see MESSAGE_ACTION_ID in the Glossary page.
required: true
requestBody:
description: Updates a message-action handler. For Deluge actions, provide `script`. For Webhook actions, provide `permissions`.
required: true
content:
application/json:
examples:
update_script_deluge:
summary: Update script - Deluge message action
value:
script: 'response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
'
update_permissions_webhook:
summary: Update permissions - Webhook message action
value:
permissions:
- chat
- message
- user
- attachments
schema:
$ref: '#/components/schemas/v3-exehandler-edit'
responses:
'200':
description: Message action handler updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/updateMessageActionHandlerResponse'
examples:
update_script_deluge:
summary: Script updated - Deluge message action
value:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: 'response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
'
function_id: '53719000002124010'
update_permissions_webhook:
summary: Permissions updated - Webhook message action
value:
url: /api/v3/messageactions/53719000002124011/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
permissions:
- chat
- message
- user
- attachments
function_id: '53719000002124011'
'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.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'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.MessageActions.UPDATE
tags:
- messageactions
get:
summary: Get details of a specific message action handler
operationId: getMessageActionHandler
description: "Retrieve the configuration and Deluge source code of the execution handler attached to a specific Message Action.\n\n Threshold limit: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| execution_handler_get_failed | \nFailed to fetch the execution handler. | \n
| execution_handler_not_found | \nSpecified handler was not found for this message action. | \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.
execution_handler, which is triggered when the message action is invoked.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: MESSAGE_ACTION_ID
in: path
name: MESSAGE_ACTION_ID
description: Unique numeric identifier of the message action. To learn how to retrieve this ID, see MESSAGE_ACTION_ID in the Glossary page.
required: true
responses:
'200':
description: Message action handler details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageActionHandlerResponse'
example:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: 'response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
'
function_id: '53719000002124010'
'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.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'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.MessageActions.READ
tags:
- messageactions
components:
schemas:
MessageActionHandlerResponse:
type: object
description: Response schema for message action handler operations.
properties:
url:
type: string
type:
type: string
example: execution_handler
data:
type: object
additionalProperties: true
updateMessageActionHandlerResponse:
type: object
description: Response schema for message action handler update operations.
properties:
url:
type: string
description: API endpoint URL for the handler resource.
type:
type: string
description: Handler type.
example: execution_handler
data:
type: object
additionalProperties: true
properties:
name:
type: string
description: Handler name.
script:
type: string
description: Updated Deluge script source code.
function_id:
type: string
description: Unique identifier of the underlying function associated with this handler.
example:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: 'response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
'
function_id: '53719000002124010'
HANDLER_TYPE_regex:
type: string
description: Type of the message action handler. Message actions support only one handler type: execution_handler, which is triggered when the action is invoked.
enum:
- execution_handler
v3-exehandler-edit:
type: object
description: Payload for updating the message action execution handler. For Deluge actions, provide `script`. For Webhook actions, provide `permissions`.
properties:
script:
type: string
description: 'Updated Deluge script for the execution handler. This script is executed when the message action is invoked by users.chat: Chat context (chat ID, type, participants).message: Message content and metadata.user: Sender's user profile details.location: Sender's location data.attachments: Attachment metadata and download info.deluge: Handler logic runs on Zoho's platform via Deluge scripts. Default when omitted.webhook: When the action is triggered, Cliq sends a POST request to your execution_url.execution_type is webhook.organization: Visible and accessible to all users within the organization.team: Visible and accessible only to members of specified teams. Requires team_ids field.personal: Visible and accessible only to the creator, but can be shared with other users by adding them as collaborators.scope is set to team. Each ID corresponds to a team within the organization.scope is team.
'
items:
type: integer
multi_selectable:
type: boolean
description: 'Determines whether the message action can be applied to multiple messages at once. If set to true, users can select multiple messages and invoke the action on all selected messages simultaneously. If false, the action can only be applied to one message at a time.
'
image:
type: string
description: 'Base64-encoded string representing a custom icon image for the message action. This icon is displayed in the message action menu alongside the action name.
'
message_types:
type: array
minItems: 1
maxItems: 3
description: "List of message types that the message action supports. This determines which types of messages the action can be applied to. Allowed values are:text: The action can be applied to text messages.link: The action can be applied to messages containing links.attachment: The action can be applied to messages with attachments.organization: Visible and accessible to all users within the organization.team: Visible and accessible only to members of specified teams. Requires team_ids field.personal: Visible and accessible only to the creator, but can be shared with other users by adding them as collaborators.scope is set to team. Each ID corresponds to a team within the organization.scope is team.
'
items:
type: integer
multi_selectable:
type: boolean
description: 'Updated multi-selection behavior. If set to true, users can select multiple messages and invoke the action on all selected messages simultaneously. If false, the action can only be applied to one message at a time.
'
image:
type: string
description: 'Updated Base64-encoded string representing a custom icon image for the message action. This icon is displayed in the message action menu alongside the action name.
'
message_types:
type: array
minItems: 1
maxItems: 3
description: "Updated list of message types that the message action supports. Allowed values are:text: The action can be applied to text messages.link: The action can be applied to messages containing links.attachment: The action can be applied to messages with attachments.