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: 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
|---|---|
| extension_plan_limit_exceeded | \nExtension plan installation limit has been reached. | \n
| extension_install_restricted_non_marketplace | \nOrganization policy restricts installing non-marketplace extensions. | \n
| extension_install_restricted | \nUser is not allowed to install this extension. | \n
| operation_failed | \nGeneral installation failure. | \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.
scope to organization for org-wide install, or team with team_ids for team-scoped install.
content:
application/json:
schema:
$ref: '#/components/schemas/extensioninstall_V3'
examples:
install_organization:
summary: Install for entire organization
value:
scope: organization
install_team:
summary: Install for specific teams
value:
scope: team
team_ids:
- 1234567890
- 9876543210
required: true
responses:
'204':
description: Extension installed successfully. No response body.
'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.Extensions.CREATE
tags:
- Extensions
put:
summary: Upgrade an extension
operationId: update_extension
description: "Upgrade an already-installed Cliq Extension to a newer version.\n\n Threshold limit: 10 requests per min per user
\n Maximum API calls allowed within one minute.
\n Lock period: 10 minutes
Cooldown period applied after threshold exhaustion.
\n
| Error Code | \nDescription | \n
|---|---|
| extension_error_not_installed | \nExtension is not installed. | \n
| app_disabled_by_owner | \nExtension is disabled by owner/developer. | \n
| extension_disabled | \nExtension is disabled by organization admin. | \n
| extension_already_installed | \nExtension is already installed at organization scope. | \n
| extension_install_restricted | \nUser is not allowed to upgrade this extension. | \n
| operation_failed | \nGeneral upgrade failure. | \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.
scope. Use organization to expand from team to org scope, or team to keep at team scope during version upgrade.
content:
application/json:
schema:
$ref: '#/components/schemas/extensionupgrade_V3'
examples:
upgrade_keep_team:
summary: Upgrade while keeping team scope
value:
scope: team
upgrade_to_organization:
summary: Upgrade and expand to organization scope
value:
scope: organization
required: true
responses:
'204':
description: Extension upgraded successfully. No response body.
'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.Extensions.UPDATE
tags:
- Extensions
/extensions/{EXTENSION_ID}/properties:
patch:
summary: Add or update extension properties
operationId: add_or_update_extension_proper
description: "Add new or update existing configuration properties for an installed Extension. Extension properties are key-value pairs used to store extension-level settings (e.g. API keys, configuration flags) that are accessible to the extension's platform components. The `extension_key` parameter is required.\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
|---|---|
| extension_property_key_length_exceeded | \nProperty key length exceeds the allowed limit. | \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.
([a-z_]+), max 30 characters. Values accept any string - use them to store API keys, webhook URLs, region identifiers, feature flags, or any other runtime configuration your extension requires. Max 1000 characters per value. Maximum 10 properties total per extension.
content:
application/json:
schema:
$ref: '#/components/schemas/appproperties'
examples:
set_single:
summary: Set a single property
value:
properties:
api_key: my_secret_api_key_value
set_multiple:
summary: Set multiple properties
value:
properties:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
required: true
responses:
'200':
description: Extension properties updated successfully. Returns only the properties that were added or updated in this request.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertiesUpdateResponse'
examples:
set_single:
summary: Single property set
value:
api_key: my_secret_api_key_value
set_multiple:
summary: Multiple properties set
value:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
'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.Extensions.UPDATE
tags:
- Extensions
get:
summary: Get extension properties
operationId: get_extension_properties
description: "Retrieve one or more application properties of an installed Extension.\n Extension properties are values associated with the extension. They are quite similar to regular data properties, wherein you map a key of type string with a value string. The main purpose is to store data configurations for the extension. They can be added, retrieved for use and deleted and even the Organization admin does not have access to view these configurations. These properties should be created and updated during extension installation and used in the extension code. Cliq supports a maximum of 10 properties per extension.
\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
|---|---|
| invalid_inputs | \nNo valid property keys were supplied. | \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.
([a-z_]+), max 30 characters per key. Maximum 10 keys per request.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'200':
description: Extension properties returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertiesGetResponse'
'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.Extensions.READ
tags:
- Extensions
/extensions/{EXTENSION_ID}/properties/{EXTENSION_PROPERTY_KEY_NAME}:
get:
summary: Get a specific extension property
operationId: get_extension_property
description: "Retrieve a single extension property of an installed extension.\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
|---|---|
| extension_property_invalid_key | \nProperty key is invalid, empty, or does not exist. | \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.
([a-z_]+), max 30 characters. To learn more, see EXTENSION_PROPERTY_KEY_NAME in the Glossary page.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'200':
description: Extension property returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertySingleResponse'
'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:
- Extensions.READ
tags:
- Extensions
delete:
summary: Delete a specific extension property
operationId: delete_extension_property
description: "Permanently delete a single extension property of an installed extension.\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
|---|---|
| extension_property_invalid_key | \nProperty key is invalid or empty. | \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.
([a-z_]+), max 30 characters. To learn more, see EXTENSION_PROPERTY_KEY_NAME in the Glossary page.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'204':
description: Extension property deleted successfully. No response body.
'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:
- Extensions.UPDATE
tags:
- Extensions
components:
schemas:
appproperties:
type: object
description: Payload for setting extension properties.
required:
- properties
properties:
properties:
type: object
description: Map of extension property keys to values.
properties:
api_key:
type: string
example: my_secret_api_key_value
extensioninstall_V3:
type: object
description: Payload for installing an extension.
required:
- scope
properties:
scope:
type: string
enum:
- organization
- team
description: "Installlation scope for the extension.organization: Extension will be available to all users within the organization. Requires admin consent.team: Extension will be available only to users within specified teams. Requires admin consent for each team.team. Maximum of 4 team IDs allowed.
'
items:
type: integer
smallalphawithspl_regex:
type: string
description: Lowercase alphanumeric string with allowed special characters (hyphens and underscores) used as extension property keys.
ExtensionPropertiesGetResponse:
type: object
description: Response returned when retrieving multiple extension properties. Keys are property names; values are their current string values.
properties:
api_key:
type: string
example: my_secret_api_key_value
region:
type: string
example: us-east
max_retries:
type: string
example: '3'
example:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
ExtensionPropertiesUpdateResponse:
type: object
description: Response returned after adding or updating extension properties. Contains only the key-value pairs that were submitted in the request.
additionalProperties:
type: string
example:
api_key: my_secret_api_key_value
encryptedappkey_regex:
type: string
description: Encrypted application key (appkey or EXTENSION_KEY) issued to a bot or extension, used as an alternative to OAuth for webhook-style authentication.
ExtensionPropertySingleResponse:
type: object
description: Response returned when retrieving a single extension property.
properties:
api_key:
type: string
example: my_secret_api_key_value
example:
api_key: my_secret_api_key_value
longid_regex:
type: string
description: Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions.
extensionupgrade_V3:
type: object
description: Payload for upgrading an installed extension.
required:
- scope
properties:
scope:
type: string
enum:
- organization
- team
description: Upgrade scope for the extension.
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/