openapi: 3.0.0
info:
title: Bots keyboardshortcuts API
description: "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
\n - Bot Handlers are the building blocks of a bot's functionality. Each handler is associated with a specific trigger event, such as receiving a direct message, being @mentioned in a channel, or a user subscribing to the bot.
\n - When the trigger event occurs, the corresponding handler executes it's script to perform actions like sending messages, making API calls, or updating data.
\n - By configuring different handlers, you can create bots that respond intelligently to various user interactions and automate complex workflows within Zoho Cliq.
\n
Types of Bot Handlers
\n \n | Handler | \n Description | \n
\n \n | Menu Handler | \n Adds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu. | \n
\n \n | Message Handler | \n Triggered when the bot receives a message. | \n
\n \n | Welcome Handler | \n Defines the greeting message sent when a user subscribes to the bot. | \n
\n \n | Mention Handler | \n Triggered when the bot is @mentioned in a chat or channel. | \n
\n \n | Incoming Webhook Handler | \n Allows external services to post messages into the bot via outgoing webhooks. | \n
\n \n | Context Handler | \n Manages multi-turn conversations, maintaining context across a user's interaction with the bot. | \n
\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.
\n - If
execution_type is not specified during bot creation, it defaults to deluge. \n - Handler logic is defined as a script field (Deluge source code) when creating or updating handlers.
\n - Suitable for teams that want to build and manage bot logic entirely within Zoho's ecosystem.
\n
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.
\n - To create a Webhook bot, set
execution_type to webhook during bot creation and provide the execution_url where event payloads should be sent. \n - Your server must be publicly accessible and able to handle incoming POST requests from Zoho Cliq.
\n - Ideal for teams seeking complete control over bot logic and possessing the resources to manage an external server. Also suitable for integrations requiring access to external databases, third-party APIs, or custom business logic that cannot be executed in Deluge.
\n
\n"
contact: {}
version: 1.0.0
servers:
- url: https://cliq.zoho.com/api/v3
description: Zoho Cliq US DC
tags:
- name: keyboardshortcuts
description: Keyboard Shortcuts Module
paths:
/settings/keyboard-shortcuts:
get:
summary: Fetch all keyboard shortcuts
operationId: fetchKeyboardShortcuts
description: "Retrieves all keyboard shortcuts for the authenticated user, including default shortcuts and any custom shortcuts. If the user does not have any custom shortcuts, all default shortcuts will be returned.\n
\n\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
\n\n \n !\n Possible Error Codes\n Click to expand\n
\n \n
\n
\n \n \n | Error Code | \n Description | \n
\n \n \n \n | invalid_oauthtoken | \n The access token is invalid or expired. | \n
\n \n | invalid_access | \n The user does not have access to this resource. | \n
\n \n | operation_failed | \n Unexpected server error while processing the request. | \n
\n \n
\n
\n
\n
Error Response Format\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
\n
\n"
responses:
'200':
description: Keyboard shortcuts were fetched successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/keyboard-shortcuts-response'
example:
keyboard_shortcuts:
basic:
search:
mac: cmd+k
windows: ctrl+k
mute:
mac: cmd+shift+m
windows: ctrl+shift+m
go_to_mentions:
mac: g+m
windows: g+m
conversation_history:
mac: cmd+shift+h
windows: ctrl+shift+h
go_home:
mac: g+h
windows: g+h
zia_search:
mac: cmd+slash
windows: ctrl+slash
add_event:
mac: cmd+shift+e
windows: ctrl+shift+e
composer:
bold:
mac: cmd+b
windows: ctrl+b
italic:
mac: cmd+i
windows: ctrl+i
underline:
mac: cmd+u
windows: ctrl+u
strikethrough:
mac: cmd+shift+x
windows: ctrl+shift+x
schedule_message:
mac: cmd+shift+s
windows: ctrl+shift+s
link:
mac: cmd+l
windows: ctrl+l
message_action:
reply:
mac: right
windows: right
forward:
mac: f
windows: f
pin:
mac: p
windows: p
copy:
mac: c
windows: c
delete:
mac: delete
windows: delete
mark_unread:
mac: u
windows: u
media:
pip:
mac: i
windows: i
add_participant:
mac: shift+equal
windows: shift+equal
go_to_chat:
mac: g+c
windows: g+c
annotate:
rotate:
mac: r
windows: r
annotate:
mac: cmd+e
windows: ctrl+e
networks: {}
custom:
chat:
- id: support-team
name: Support Team
mac: cmd+option+c
windows: ctrl+alt+c
widget: []
snippet: []
'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.Profile.READ
tags:
- keyboardshortcuts
put:
summary: Update keyboard shortcuts
operationId: updateKeyboardShortcuts
description: "Updates default or custom keyboard shortcuts for the authenticated user. The shortcut details must be passed in JSON format.\n
\n\n - Default shortcuts: Provide the category (e.g.,
basic, composer, message_action, annotate, media, networks), the shortcut name, and the OS key (windows or mac). \n - Custom shortcuts:\n
\n - Chat / Widget: Requires an
id (chat ID or widget ID respectively) along with the OS key. \n - Snippet: Requires a
name and message along with the OS key. \n
\n \n - Overlap validation: When updating, the new shortcut key is validated against existing shortcuts to prevent overlap. If the key is already mapped to another action, an error is returned.
\n
\n
\n\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
\n\n \n !\n Possible Error Codes\n Click to expand\n
\n \n
\n
\n \n \n | Error Code | \n Description | \n
\n \n \n \n | shortcut_overlap | \n Shortcut key is already mapped to another action. | \n
\n \n | invalid_shortcut_payload | \n Payload structure is invalid. | \n
\n \n | invalid_widget_id | \n Provided widget ID does not exist. | \n
\n \n | invalid_chat_id | \n Provided chat ID does not exist. | \n
\n \n
\n
\n
\n
Error Response Format\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
\n
\n"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update-keyboard-shortcuts-request'
examples:
update_default_shortcut:
summary: Update a default shortcut key mapping
value:
keyboard_shortcuts:
basic:
search:
mac: cmd+k
windows: ctrl+k
composer:
bold:
mac: cmd+b
windows: ctrl+b
add_custom_chat_shortcut:
summary: Add a custom chat shortcut
value:
custom:
chat:
- id: support-team
name: Support Team
mac: cmd+option+c
windows: ctrl+alt+c
add_custom_widget_shortcut:
summary: Add a custom widget shortcut
value:
custom:
widget:
- id: calendar-widget
name: Calendar Widget
mac: cmd+option+w
windows: ctrl+alt+w
responses:
'200':
description: Keyboard shortcuts were updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/no-response'
'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.Profile.UPDATE
tags:
- keyboardshortcuts
delete:
summary: Delete keyboard shortcuts customization
operationId: deleteKeyboardShortcuts
description: "Resets all custom shortcuts to defaults, or deletes only the specific mappings provided in the request payload. To delete a single shortcut key, pass the same input structure as the update (PUT) request with the target shortcut details.\n
\n\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
\n\n \n !\n Possible Error Codes\n Click to expand\n
\n \n
\n
\n \n \n | Error Code | \n Description | \n
\n \n \n \n | invalid_shortcut_payload | \n Payload structure is invalid for targeted deletion. | \n
\n \n | operation_failed | \n Unexpected server error while deleting custom shortcuts. | \n
\n \n
\n
\n
\n
Error Response Format\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
\n
\n"
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/delete-keyboard-shortcuts-request'
examples:
delete_specific_custom:
summary: Delete a specific custom chat shortcut
value:
custom:
chat:
- id: support-team
delete_all_custom:
summary: Delete all custom shortcuts in bulk
value:
type: custom
reset_all_defaults:
summary: Reset all default shortcuts to system defaults
value:
type: default
responses:
'204':
description: Keyboard shortcuts reset/deletion completed 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.Profile.DELETE
tags:
- keyboardshortcuts
components:
schemas:
update-keyboard-shortcuts-request:
type: object
additionalProperties: true
properties:
basic:
type: object
description: Basic navigation shortcuts to update (e.g., interacting with elements, moving sections, moving focus).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
composer:
type: object
description: Message composer shortcuts to update (e.g., bold, italic, underline).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
message_action:
type: object
description: Message action shortcuts to update (e.g., star message, add reaction, go to writing assistant).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
annotate:
type: object
description: Annotation tool shortcuts to update (e.g., rectangle, add line, text).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
media:
type: object
description: Media call shortcuts to update (e.g., mute/unmute, video on/off, temporary unmute).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
networks:
type: object
description: Network navigation shortcuts to update (e.g., navigate between networks).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
custom:
type: object
description: "Custom shortcuts to update. To update a custom shortcut, provide the complete details of the shortcut (including the new key mapping and associated chat/widget/snippet information). Partial updates are not supported for custom shortcuts.\nAllowed custom shortcut types:\n\n chat: Requires an id (chat ID) along with the new shortcut key mapping.widget: Requires an id (widget ID) along with the new shortcut key mapping.snippet: Requires a name, message, and the new shortcut key mapping.
\n"
additionalProperties: true
no-response:
type: object
properties:
status:
type: string
example: success
keyboard-shortcuts-object:
type: object
additionalProperties: true
properties:
basic:
type: object
description: Basic navigation shortcuts (e.g., interacting with elements, moving sections, moving focus).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
composer:
type: object
description: Message composer shortcuts (e.g., bold, italic, underline).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
message_action:
type: object
description: Message action shortcuts (e.g., star message, add reaction, go to writing assistant).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
annotate:
type: object
description: Annotation tool shortcuts (e.g., rectangle, add line, text).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
media:
type: object
description: Media call shortcuts (e.g., mute/unmute, video on/off, temporary unmute).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
networks:
type: object
description: Network navigation shortcuts (e.g., navigate between networks).
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
custom:
type: object
properties:
chat:
type: array
items:
$ref: '#/components/schemas/custom-chat-or-widget-entry'
widget:
type: array
items:
$ref: '#/components/schemas/custom-chat-or-widget-entry'
snippet:
type: array
items:
$ref: '#/components/schemas/custom-snippet-entry'
custom-chat-or-widget-entry:
type: object
properties:
name:
type: string
description: Name of the chat or widget.
example: Support Team
id:
type: string
description: Chat or widget identifier.
example: support-team
mac:
type: string
description: Shortcut mapping for Mac (e.g., cmd+option+c).
example: cmd+option+c
windows:
type: string
description: Shortcut mapping for Windows (e.g., ctrl+alt+c).
example: ctrl+alt+c
required:
- id
delete-keyboard-shortcuts-request:
type: object
additionalProperties: true
properties:
basic:
type: object
description: Basic navigation shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
composer:
type: object
description: Message composer shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
message_action:
type: object
description: Message action shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
annotate:
type: object
description: Annotation tool shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
media:
type: object
description: Media call shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
networks:
type: object
description: Network navigation shortcuts to delete/reset.
additionalProperties:
$ref: '#/components/schemas/os-shortcut'
custom:
type: object
description: 'Custom shortcuts to delete. Provide the id of each chat or widget shortcut to remove.
'
additionalProperties: true
type:
type: string
enum:
- custom
- default
description: 'Specifies a bulk delete operation. Use custom to remove all custom shortcuts, or default to reset all default shortcuts to their system defaults. Omit this field to delete only the specific shortcuts provided in the payload.
'
example: custom
custom-snippet-entry:
type: object
properties:
name:
type: string
description: Name of snippet shortcut.
example: OOO Snippet
message:
type: string
description: Snippet content to be sent when the shortcut is triggered.
example: I'm currently out of office. Will get back to you soon!
mac:
type: string
description: Shortcut mapping for Mac (e.g., cmd+option+o).
example: cmd+option+o
windows:
type: string
description: Shortcut mapping for Windows (e.g., ctrl+alt+o).
example: ctrl+alt+o
required:
- name
- message
os-shortcut:
type: object
properties:
windows:
type: string
description: Shortcut mapping for Windows (e.g., ctrl+k, ctrl+shift+m).
example: ctrl+k
mac:
type: string
description: Shortcut mapping for Mac (e.g., cmd+k, cmd+shift+m).
example: cmd+k
keyboard-shortcuts-response:
type: object
properties:
keyboard_shortcuts:
$ref: '#/components/schemas/keyboard-shortcuts-object'
required:
- keyboard_shortcuts
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/