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 slash command. Commands are invoked by users from the message compose bar by typing a forward slash followed by the command name (e.g. /report).\n
\n\n Slash Commands support two execution types:\n
\nexecution_url. Your server processes the event and returns the response. Best for commands that need to reach external APIs or custom backends.\n Pass execution_type: \"webhook\" and a valid execution_url to create a Webhook command. If execution_type is omitted, it defaults to deluge.\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
|---|---|
| Security validation error | \nThe name field is required. | \n
| Security validation error | \nThe hint field is required. | \n
| Security validation error | \nThe scope field is required. | \n
| Security validation error | \nThe name must not exceed 30 characters. | \n
| Security validation error | \nThe hint must not exceed 128 characters. | \n
| Security validation error | \nThe description must not exceed 300 characters. | \n
| Security validation error | \nA command cannot have more than 5 options. | \n
| Security validation error | \nEach option value must not exceed 100 characters. | \n
| command_name_already_exists | \nA command with this name already exists. | \n
| command_creation_limit_exceeded | \nThe maximum number of slash commands allowed has been reached. | \n
| command_not_valid | \nThe provided command data is invalid or malformed. | \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 field of the API response and can be used for incremental synchronization.
'
required: false
- schema:
description: ''
type: integer
in: query
name: limit
description: 'Maximum number of commands to return in the response. This can be used to control pagination and manage response size.
'
required: false
- schema:
description: ''
$ref: '#/components/schemas/base64_regex'
in: query
name: next_token
description: 'Pagination token to retrieve the next page of results. This token is returned in the next_token field of the API response when there are more results available beyond the current page.
'
required: false
responses:
'200':
description: List of commands returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/list-all-slash-commands-response'
example:
url: /api/v3/commands
type: command
sync_token: MTB8MTc3NzM2MDM5OTQ5Mnw=
data:
- name: report
id: '227828000000128011'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Generate a sales or activity report
status: enabled
type: custom
description: Generates a report for the specified date range and team
scope: organization
options:
type: Report type (e.g. sales, activity, attendance)
period: Date range (e.g. today, this_week, last_month)
- name: ticket
id: '227828000000128009'
handlers:
- type: execution_handler
- type: suggestion_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Create or look up a support ticket
status: enabled
max_suggestions: 5
type: custom
description: Creates a new support ticket or retrieves an existing one by ID
scope: team
options:
action: Action to perform (create or lookup)
priority: Ticket priority (low, medium, high, critical)
'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.Commands.READ
tags:
- slashcommands
/commands/{SLASH_COMMAND_ID}:
patch:
summary: Update a slash command
operationId: editing_extension_command
description: "Update the configuration of an existing slash command.\n\n All fields are optional. Only the fields you provide will be updated; omitted fields remain unchanged.\n
\n\n For Webhook commands, you can update the execution_url independently at any time to redirect the command to a new server endpoint without recreating it.\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
|---|---|
| command_not_found | \nCommand with the specified ID does not exist. | \n
| command_name_already_exists | \nA command with this name already exists. | \n
| command_not_valid | \nThe provided command data is invalid or malformed. | \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
| Error Code | \nDescription | \n
|---|---|
| command_not_found | \nCommand with the specified ID was not found. | \n
| command_not_found | \nYou do not have permission to view this command. | \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
|---|---|
| command_not_found | \nCommand 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 Add a new handler to an existing slash command. Commands support two handler types:\n
\n\n The field you provide depends on the command's execution type:\n
\nscript field with the Deluge source code to execute when the handler fires.permissions field - an array of data attributes your server needs to receive in the webhook payload. Do not pass script for Webhook commands.Permissions availability by handler type
\n| Handler | \nattachments | \n chat | \n location | \n user | \n
|---|---|---|---|---|
execution_handler | \n ✓ | \n✓ | \n✓ | \n✓ | \n
suggestion_handler | \n - | \n✓ | \n✓ | \n✓ | \n
Note: attachments is not available for suggestion_handler. All permissions are available for execution_handler.
\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_create_failed | \nFailed to create the handler. | \n
| execution_handler_data_required | \nRequired field missing. | \n
| execution_handler_data_invalid | \nHandler data is invalid. | \n
| invalid_inputs | \nInvalid handler type or bad request body. | \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.permissions array to change which data attributes are forwarded to your server.\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 handler. | \n
| execution_handler_not_found | \nHandler not found for this component. | \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: The main handler that executes when the command is invoked.suggestion_handler: The handler that generates autocomplete suggestions as users type the command.\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 handler. | \n
| execution_handler_not_found | \nHandler was not found for this command. | \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: The main handler that executes when the command is invoked.suggestion_handler: The handler that generates autocomplete suggestions as users type the command.\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_delete_failed | \nFailed to delete the handler. | \n
| default_handler_delete_not_allowed | \nDefault handlers cannot be deleted. | \n
| execution_handler_not_found | \nHandler was not found for this command. | \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.
suggestion_handler: The handler that generates autocomplete suggestions as users type the command.suggestion_handler can be deleted. The execution_handler is mandatory for a slash command and cannot be removed. \n"
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: SLASH_COMMAND_ID
in: path
name: SLASH_COMMAND_ID
description: Unique numeric identifier of the slash command. To learn how to retrieve this ID, see SLASH_COMMAND_ID in the Glossary page.
required: true
responses:
'204':
description: No Content. Command handler deleted successfully.
'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.Commands.UPDATE
tags:
- slashcommands
components:
schemas:
update-slash-command-request-body:
type: object
description: Payload for updating a slash command. All fields are optional; only the fields provided will be updated.
properties:
execution_url:
type: string
maxLength: 225
description: 'Updated server URL where Cliq will forward handler events. Applicable only for Webhook commands.location, unit).\"City to check weather for\").{\"options\": {\"location\": \"City to check weather for\", \"unit\": \"Temperature unit: celsius or fahrenheit\"}}organization: Command is available to all users in the organization.team: Command is restricted to specific teams. Requires team_ids field.personal: Command is only available to the creator.scope is set to team. Each ID corresponds to a team within the organization.scope is being changed to team.
'
items:
type: integer
image:
type: string
maxLength: 204800000
description: "Updated base64 encoded image used as the command icon. This icon will be displayed next to the command in the slash command picker.deluge: Handler logic runs on Zoho's platform via Deluge scripts. Default when omitted.webhook: Handler events are forwarded to your execution_url as POST requests.execution_type is webhook.location, unit).\"City to check weather for\").{\"options\": {\"location\": \"City to check weather for\", \"unit\": \"Temperature unit: celsius or fahrenheit\"}}organization: Command is available to all users in the organization.team: Command is restricted to specific teams. Requires team_ids field.personal: Command is only available to the creator.scope is set to team. Each ID corresponds to a team within the organization.scope is team.
'
items:
type: integer
image:
type: string
maxLength: 204800000
description: "Base64 encoded image used as the command icon. This icon will be displayed next to the command in the slash command picker and can help users visually identify the command.execution_handler: Executes on command invocation.suggestion_handler: Executes to provide autocomplete suggestions as users type the command.script for Webhook commands - use permissions instead.
'
permissions:
type: array
maxItems: 5
description: "List of data attributes to forward to your server in the webhook payload when the handler fires.permissions for Deluge commands - use script instead.attachments: File attachment metadata. Not available for suggestion_handler.chat: Chat context (chat ID, type, participants).location: Sender's location data.user: Sender's user profile details.execution_handler (fires on command invocation), suggestion_handler (fires to generate autocomplete suggestions).
'
v3-exehandler-edit:
type: object
description: Payload for updating an existing handler. For Deluge commands, provide `script`. For Webhook commands, provide `permissions`.
properties:
script:
type: string
description: 'Updated Deluge script source code for the handler.attachments, chat, location, user. Note: attachments is not available for suggestion_handler.
'
items:
type: string
enum:
- attachments
- chat
- location
- user
base64_regex:
type: string
description: Base64-encoded pagination or sync token used for cursor-based pagination and incremental data sync.
SlashCommandResponse:
type: object
description: Slash Commands API response envelope.
properties:
url:
type: string
type:
type: string
data:
type: object
additionalProperties: true
example:
url: /api/v3/commands/227828000000128009
type: command
data:
name: greet
id: '227828000000128009'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Send a greeting message
status: enabled
max_suggestions: 5
type: custom
description: Sends a customizable greeting to a user or channel
scope: organization
options:
user: The user to greet
msg: Custom greeting message
list-all-slash-commands-response:
type: object
description: Response schema for listing slash commands.
properties:
url:
type: string
example: /api/v3/commands
type:
type: string
example: command
sync_token:
type: string
description: Token for incremental sync. Pass this in the next request to retrieve only commands updated since this response.
example: MTB8MTc3NzM2MDM5OTQ5Mnw=
next_token:
type: string
description: Pagination token for the next page of results.
data:
type: array
items:
type: object
properties:
name:
type: string
id:
type: string
handlers:
type: array
items:
type: object
properties:
type:
type: string
creator:
type: object
properties:
name:
type: string
id:
type: string
execution_type:
type: string
example: deluge
hint:
type: string
status:
type: string
example: enabled
type:
type: string
example: custom
description:
type: string
scope:
type: string
enum:
- organization
- team
- personal
max_suggestions:
type: integer
options:
type: object
additionalProperties:
type: string
example:
url: /api/v3/commands
type: command
sync_token: MTB8MTc3NzM2MDM5OTQ5Mnw=
data:
- name: report
id: '227828000000128011'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Generate a sales or activity report
status: enabled
type: custom
description: Generates a report for the specified date range and team
scope: organization
options:
type: Report type (e.g. sales, activity, attendance)
period: Date range (e.g. today, this_week, last_month)
- name: ticket
id: '227828000000128009'
handlers:
- type: execution_handler
- type: suggestion_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Create or look up a support ticket
status: enabled
max_suggestions: 5
type: custom
description: Creates a new support ticket or retrieves an existing one by ID
scope: team
options:
action: Action to perform (create or lookup)
priority: Ticket priority (low, medium, high, critical)
longid_regex:
type: string
description: Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions.
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoCliq.Bots.READ: Read Bot Information
ZohoCliq.Bots.CREATE: Create Bots
ZohoCliq.Bots.UPDATE: Update Bots
ZohoCliq.Bots.DELETE: Delete Bots
ZohoCliq.Webhooks.CREATE: Post messages to conversations via webhooks
ZohoCliq.BotMessages.CREATE: Send messages via bot incoming webhooks
ZohoCliq.Channels.UPDATE: Update Channel Settings
externalDocs:
description: Find out more about Zoho Cliq APIs V3
url: https://www.zoho.com/cliq/help/restapi/v3/