openapi: 3.0.0
info:
title: Slash Commands
version: '3.0'
description: |
Slash Commands are custom commands that users invoke directly from the Zoho Cliq message compose bar by typing a forward slash followed by the command name (e.g. /report, /deploy, /leave). They allow users to trigger automation, fetch data, or initiate workflows without leaving the conversation.
For more information, refer to the Slash Commands Help Documentation.
Command Handlers
Command handlers define the logic that runs when a user invokes a slash command. Each command supports up to two handler types:
| Handler |
Description |
execution_handler |
Runs when the user submits the command. Processes the input, performs actions (API calls, data lookups, message posts), and returns a response rendered back in the chat. |
suggestion_handler |
Runs as the user types the command argument to populate a real-time autocomplete dropdown with context-aware suggestions. Triggered only when the command includes a text argument field. |
Command Scope
- organization - The command is available to all users across the organization.
- team - The command is restricted to members of specified teams.
- personal - The command is visible only to the creator.
What can you do with the Slash Commands API?
With the Slash Commands API, you can programmatically create and manage slash commands, configure execution and suggestion handlers, retrieve command details, and manage command visibility across the organization - all without using the Cliq Developer console.
Each command has an execution_type that defines how its handlers run when invoked. The Slash Commands API supports two execution types:
Deluge Commands (default)
Handler logic is written in Deluge and runs entirely within Zoho's platform. No external server is required.
- If
execution_type is not specified during command creation, it defaults to deluge.
- Handler logic is defined using the
script field (Deluge source code) when creating or updating handlers.
- Suitable for teams that want to build and manage command logic entirely within Zoho's ecosystem.
Webhook Commands
When a user invokes the command, Zoho Cliq sends an HTTP POST request to the execution_url you configure. Your server processes the event and returns a response that Cliq renders back in the chat.
- To create a Webhook command, set
execution_type to webhook and provide the execution_url.
- Handler permissions (
attachments, chat, location, user) control which data attributes are included in the webhook payload. Not all permissions apply to every handler type - refer to the permissions table in the Create a handler endpoint.
- Ideal for commands that need to integrate with external APIs, databases, or custom backend services.
externalDocs:
description: Find out more about Zoho Cliq Platform APIs
url: https://www.zoho.com/cliq/help/platform/getting-started-with-cliq-platform.html
servers:
- url: https://cliq.zoho.com/api/v3
description: Zoho Cliq US DC
tags:
- name: slashcommands
description: Slash Commands Module
paths:
/commands:
post:
summary: Create a slash command
operationId: creating_extension_command
description: |
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).
Slash Commands support two execution types:
- Deluge (default): Handler logic runs on Zoho's platform via Deluge scripts. No external server needed. Best for Zoho-native integrations.
- Webhook: When the command is invoked, Cliq sends a POST request to your
execution_url. Your server processes the event and returns the response. Best for commands that need to reach external APIs or custom backends.
Pass execution_type: "webhook" and a valid execution_url to create a Webhook command. If execution_type is omitted, it defaults to deluge.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| Security validation error |
The name field is required. |
| Security validation error |
The hint field is required. |
| Security validation error |
The scope field is required. |
| Security validation error |
The name must not exceed 30 characters. |
| Security validation error |
The hint must not exceed 128 characters. |
| Security validation error |
The description must not exceed 300 characters. |
| Security validation error |
A command cannot have more than 5 options. |
| Security validation error |
Each option value must not exceed 100 characters. |
| command_name_already_exists |
A command with this name already exists. |
| command_creation_limit_exceeded |
The maximum number of slash commands allowed has been reached. |
| command_not_valid |
The provided command data is invalid or malformed. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters: []
requestBody:
description: Creates a slash command. Provide `name`, `hint`, and `scope`. Set `execution_type` to `webhook` and include `execution_url` for a Webhook command.
required: true
content:
application/json:
examples:
deluge_command:
summary: Deluge slash command
value:
name: support
hint: Raise a support ticket
scope: organization
execution_type: deluge
description: Creates a ZohoDesk ticket from the chat interface
webhook_command:
summary: Webhook slash command
value:
name: deploy
hint: Trigger a deployment pipeline
scope: organization
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/commands/handler
description: Triggers a Jenkins deployment from Cliq
schema:
$ref: '#/components/schemas/create-slash-command-request-body'
responses:
'200':
description: Slash command created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
examples:
deluge_command:
summary: Deluge slash command response
value:
url: /api/v3/commands
type: command
data:
name: support
id: '227828000000128009'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Raise a support ticket
status: enabled
type: custom
description: Creates a ZohoDesk ticket from the chat interface
scope: organization
webhook_command:
summary: Webhook slash command response
value:
url: /api/v3/commands
type: command
data:
name: deploy
id: '227828000000129001'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/commands/handler
hint: Trigger a deployment pipeline
status: enabled
type: custom
description: Triggers a Jenkins deployment from Cliq
scope: organization
'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.CREATE
tags:
- slashcommands
get:
summary: List all commands
operationId: get_list_of_commands
description: |
Retrieve a paginated list of all slash commands.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
parameters:
- schema:
description: ''
$ref: '#/components/schemas/base64_regex'
in: query
name: sync_token
description: |
Sync token to fetch only commands that have changed since the last request. This token is returned in the 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.
All fields are optional. Only the fields you provide will be updated; omitted fields remain unchanged.
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.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| command_not_found |
Command with the specified ID does not exist. |
| command_name_already_exists |
A command with this name already exists. |
| command_not_valid |
The provided command data is invalid or malformed. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- 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
requestBody:
description: Updates a slash command. Send only fields to change; omitted fields remain unchanged. For Webhook commands, use `execution_url` to update the server endpoint.
required: true
content:
application/json:
examples:
update_details:
summary: Update command details
value:
hint: Raise a support ticket - updated
description: Updated description via API
scope: organization
max_suggestions: 5
update_webhook_url:
summary: Update webhook execution URL
value:
execution_url: https://api.yourcompany.com/cliq/commands/updated-handler
schema:
$ref: '#/components/schemas/update-slash-command-request-body'
responses:
'200':
description: Command updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
examples:
update_details:
summary: Deluge command updated
value:
url: /api/v3/commands/227828000000128009
type: command
data:
name: support
id: '227828000000128009'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: deluge
hint: Raise a support ticket - updated
status: enabled
type: custom
description: Updated description via API
scope: organization
update_webhook_url:
summary: Webhook command execution URL updated
value:
url: /api/v3/commands/227828000000129001
type: command
data:
name: deploy
id: '227828000000129001'
handlers:
- type: execution_handler
creator:
name: Ryan West
id: '119440882'
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/commands/updated-handler
hint: Trigger a deployment pipeline
status: enabled
type: custom
description: Triggers a Jenkins deployment from Cliq
scope: organization
'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
get:
summary: Get a command
operationId: get_a_command
description: |
Retrieve details of a specific slash command.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| command_not_found |
Command with the specified ID was not found. |
| command_not_found |
You do not have permission to view this command. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- 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:
'200':
description: Command details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
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
'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
delete:
summary: Delete a slash command
operationId: deleting_extension_command
description: |
Permanently delete a custom Slash Command and all its associated handlers. The command will be removed from all accessible scopes and can no longer be invoked by users. This action is irreversible.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| command_not_found |
Command with the specified ID was not found. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- 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 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.DELETE
tags:
- slashcommands
/commands/{SLASH_COMMAND_ID}/handlers:
post:
summary: Create a handler for a specific command
operationId: createCommandHandler
description: |
Add a new handler to an existing slash command. Commands support two handler types:
- Execution handler: Executes the command's primary function when invoked.
- Suggestion handler: Provides dynamic autocomplete suggestions as users type the command.
The field you provide depends on the command's execution type:
- Deluge command: Provide the
script field with the Deluge source code to execute when the handler fires.
- Webhook command: Provide the
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
| Handler |
attachments |
chat |
location |
user |
execution_handler |
✓ |
✓ |
✓ |
✓ |
suggestion_handler |
- |
✓ |
✓ |
✓ |
Note: attachments is not available for suggestion_handler. All permissions are available for execution_handler.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| execution_handler_create_failed |
Failed to create the handler. |
| execution_handler_data_required |
Required field missing. |
| execution_handler_data_invalid |
Handler data is invalid. |
| invalid_inputs |
Invalid handler type or bad request body. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- 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
requestBody:
description: Creates a slash-command handler. For Deluge commands, provide `type` and `script`. For Webhook commands, provide `type` and `permissions`.
required: true
content:
application/json:
examples:
execution_handler_deluge:
summary: Execution handler - Deluge command
description: Provide `script` with the Deluge source code. Runs directly on Zoho's platform.
value:
type: execution_handler
script: |
response = Map();
user = info.get("user_info").get("name");
response.put("text", "Hello, " + user + "! Support ticket created.");
return response;
execution_handler_webhook:
summary: Execution handler - Webhook command
description: Provide `permissions` to specify the data your server needs. Cliq will forward these to your `execution_url`.
value:
type: execution_handler
permissions:
- chat
- user
suggestion_handler_deluge:
summary: Suggestion handler - Deluge command
description: Runs to generate autocomplete suggestions as users type the command.
value:
type: suggestion_handler
script: |
suggestions = List();
suggestions.add({"value": "create", "label": "Create a new ticket"});
suggestions.add({"value": "lookup", "label": "Look up an existing ticket"});
return {"suggestions": suggestions};
suggestion_handler_webhook:
summary: Suggestion handler - Webhook command
description: Webhook commands route suggestion requests to your `execution_url` with the configured permissions.
value:
type: suggestion_handler
permissions:
- chat
- user
schema:
$ref: '#/components/schemas/v3-exehandler-create'
responses:
'200':
description: Command handler created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
examples:
execution_handler_deluge:
summary: Execution handler created - Deluge
value:
url: /api/v3/commands/227828000000128009/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
user = info.get("user_info").get("name");
response.put("text", "Hello, " + user + "! Support ticket created.");
return response;
function_id: '227828000000128009'
execution_handler_webhook:
summary: Execution handler created - Webhook
value:
url: /api/v3/commands/227828000000129001/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
permissions:
- chat
- user
function_id: '227828000000129001'
suggestion_handler_deluge:
summary: Suggestion handler created - Deluge
value:
url: /api/v3/commands/227828000000128009/handlers/suggestion_handler
type: suggestion_handler
data:
name: suggestion_handler
script: |
suggestions = List();
suggestions.add({"value": "create", "label": "Create a new ticket"});
suggestions.add({"value": "lookup", "label": "Look up an existing ticket"});
return {"suggestions": suggestions};
function_id: '227828000000128009'
suggestion_handler_webhook:
summary: Suggestion handler created - Webhook
value:
url: /api/v3/commands/227828000000129001/handlers/suggestion_handler
type: suggestion_handler
data:
name: suggestion_handler
permissions:
- chat
- user
function_id: '227828000000129001'
'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
/commands/{SLASH_COMMAND_ID}/handlers/{COMMAND_HANDLER_TYPE}:
patch:
summary: Update a handler for a specific command
operationId: updateCommandHandler
description: |
Update a handler for a specific slash command. What you provide depends on the command's execution type:
- Deluge command: Update the
script attribute with the revised Deluge source code.
- Webhook command: Update the
permissions array to change which data attributes are forwarded to your server.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| execution_handler_update_failed |
Failed to update the handler. |
| execution_handler_not_found |
Handler not found for this component. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- schema:
description: ''
$ref: '#/components/schemas/COMMAND_HANDLER_TYPE_regex'
example: COMMAND_HANDLER_TYPE
in: path
name: COMMAND_HANDLER_TYPE
description: |
Type of the handler to update.
Allowed values:
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.
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
requestBody:
description: Updates a command handler. For Deluge commands, provide `script`. For Webhook commands, provide `permissions`.
required: true
content:
application/json:
examples:
update_script_deluge:
summary: Update script - Deluge command
description: Update the Deluge script that runs when the command is invoked.
value:
script: |
response = Map();
user = info.get("user_info").get("name");
response.put("text", "Hello, " + user + "! Updated ticket handler.");
return response;
update_permissions_webhook:
summary: Update permissions - Webhook command
description: Update the data attributes sent to your server when the handler fires.
value:
permissions:
- chat
- location
- user
schema:
$ref: '#/components/schemas/v3-exehandler-edit'
responses:
'200':
description: Command handler updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
examples:
update_script_deluge:
summary: Script updated - Deluge command
value:
url: /api/v3/commands/227828000000128009/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
user = info.get("user_info").get("name");
response.put("text", "Hello, " + user + "! Updated ticket handler.");
return response;
function_id: '227828000000128009'
update_permissions_webhook:
summary: Permissions updated - Webhook command
value:
url: /api/v3/commands/227828000000129001/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
permissions:
- chat
- location
- user
function_id: '227828000000129001'
'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
get:
summary: Get details of a specific command handler
operationId: get_details_of_a_specific_comm
description: |
Retrieve the configuration and deluge source code of a specific handler associated with a slash command.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| execution_handler_get_failed |
Failed to fetch the handler. |
| execution_handler_not_found |
Handler was not found for this command. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- schema:
description: ''
$ref: '#/components/schemas/COMMAND_HANDLER_TYPE_regex'
example: COMMAND_HANDLER_TYPE
in: path
name: COMMAND_HANDLER_TYPE
description: |
Type of the handler to retrieve.
Allowed values:
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.
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:
'200':
description: Command handler details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SlashCommandResponse'
example:
url: /api/v3/commands/227828000000128009/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
user = info.get("user_info").get("name");
response.put("text", "Hello, " + user + "! Command executed successfully.");
return response;
function_id: '227828000000128009'
'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
delete:
summary: Delete a handler from a specific command
operationId: deleteCommandHandler
description: |
Permanently remove a specified handler from a slash command. This action is irreversible, and once removed, the associated deluge code is lost, and the handler will no longer activate on its trigger event.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
!
Possible Error Codes
Click to expand
| Error Code |
Description |
| execution_handler_delete_failed |
Failed to delete the handler. |
| default_handler_delete_not_allowed |
Default handlers cannot be deleted. |
| execution_handler_not_found |
Handler was not found for this command. |
Error Response Format
When an error occurs, the API returns a JSON response in this format:
{"message": "A human-readable description of the error.", "code": "error_code"}
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
parameters:
- schema:
description: ''
$ref: '#/components/schemas/COMMAND_HANDLER_TYPE_regex'
example: COMMAND_HANDLER_TYPE
in: path
name: COMMAND_HANDLER_TYPE
description: |
Name of the slash command handler.
Allowed value:
suggestion_handler: The handler that generates autocomplete suggestions as users type the command.
Note: Only the suggestion_handler can be deleted. The execution_handler is mandatory for a slash command and cannot be removed.
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:
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
ExecutionRecordResponse:
type: object
description: Response envelope for slash command handler execution records.
properties:
status:
type: string
description: HTTP status text of the response.
example: OK
code:
type: integer
description: HTTP status code of the response.
example: 200
data:
type: object
properties:
logs:
type: array
description: List of execution log entries.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the execution record.
time:
type: integer
format: int64
description: Epoch timestamp (ms) when the handler was executed.
executionTime:
type: integer
description: Time taken to execute the handler, in milliseconds.
output:
type: string
description: Output returned by the handler script (serialized as a JSON string).
user:
type: object
description: Details of the user who triggered the command execution.
properties:
id:
type: string
zoho_user_id:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
example:
status: OK
code: 200
data:
logs:
- user:
zoho_user_id: '697322516'
last_name: Raman
email: priya.raman@zylker.com
first_name: Priya
id: '697322516'
output: '{}'
time: 1770628936698
executionTime: 183
id: d37d7b20-0598-11f1-8871-fb8adfa476c7
- user:
zoho_user_id: '697322516'
last_name: Raman
email: priya.raman@zylker.com
first_name: Priya
id: '697322516'
output: '{}'
time: 1770628887877
executionTime: 179
id: b66694e0-0598-11f1-b90c-55af9267af80
v3-exehandler-create:
type: object
description: Payload for creating a new handler. For Deluge commands, provide `type` and `script`. For Webhook commands, provide `type` and `permissions`.
required:
- type
properties:
type:
type: string
enum:
- execution_handler
- suggestion_handler
description: |
Type of the handler to create. Accepted values:
execution_handler: Executes on command invocation.suggestion_handler: Executes to provide autocomplete suggestions as users type the command.
script:
type: string
description: |
Deluge script source code for the handler.
Maximum size: 250KB
Note: Applicable only for Deluge commands. Do not pass 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.
Note: Applicable only for Webhook commands. Do not pass permissions for Deluge commands - use script instead.
Maximum: 5 permissions per handler.
Allowed values:
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.
Refer to the permissions availability table in the Create a handler endpoint for per-handler availability.
items:
type: string
enum:
- attachments
- chat
- location
- user
longid_regex:
type: string
description: Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions.
COMMAND_HANDLER_TYPE_regex:
type: string
enum:
- execution_handler
- suggestion_handler
description: |
Name of a slash command handler. Accepted values: execution_handler (fires on command invocation), suggestion_handler (fires to generate autocomplete suggestions).
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.
This field can be updated independently to redirect the command to a new endpoint without any other changes.
Maximum length: 225 characters.
example: https://api.yourcompany.com/cliq/commands/updated-handler
name:
type: string
maxLength: 30
description: |
Updated name of the slash command. This is the text users type after "/" to invoke the command. Must be unique within the command's scope.
Maximum length: 30 characters
Allowed characters: lowercase letters, numbers, and underscores only. No spaces or special characters allowed.
hint:
type: string
maxLength: 128
description: |
Updated hint shown in the slash command picker to help users understand the command's purpose. Should be concise and descriptive.
Maximum length: 128 characters
description:
type: string
maxLength: 300
description: |
Updated detailed description of the slash command's functionality. This can provide more in-depth information than the hint and may be shown in command documentation or tooltips.
Maximum length: 300 characters
options:
type: object
description: |
Updated options map. Options are additional properties which can alter the output of a /command based on the user's requirements.
Maximum size: 5 key-value pairs.
- Key: Option name - identifies the option (e.g.
location, unit).
- Value: Option description - explains what the option does (e.g.
"City to check weather for").
Example syntax:
{"options": {"location": "City to check weather for", "unit": "Temperature unit: celsius or fahrenheit"}}
additionalProperties:
type: string
maxLength: 100
scope:
type: string
enum:
- organization
- team
- personal
description: |
Updated access scope of the slash command. Determines who can see and use the command.
Allowed values:
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.
team_ids:
type: array
maxItems: 4
description: |
Updated list of team_ids that are allowed to access the command when scope is set to team. Each ID corresponds to a team within the organization.
Maximum items: 4 team IDs can be specified.
This field is required if 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.
Image requirements:
- Format: PNG or JPEG
- Maximum size: 100 KB
- Recommended dimensions: 64x64 pixels for optimal display
max_suggestions:
type: integer
maximum: 5
description: |
Updated maximum number of autocomplete suggestions that can be selected by the user when the command is typed.
Maximum value: 5 suggestions
example:
hint: Send a personalized greeting - updated
description: Sends a customizable greeting to a user or channel
scope: organization
options:
user: The user to greet
msg: Custom greeting message
max_suggestions: 5
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.
Maximum size: 250KB
Note: Applicable only for Deluge commands.
permissions:
type: array
maxItems: 5
description: |
Updated list of data attributes to forward to your server in the webhook payload.
Note: Applicable only for Webhook commands.
Allowed values: attachments, chat, location, user. Note: attachments is not available for suggestion_handler.
items:
type: string
enum:
- attachments
- chat
- location
- user
create-slash-command-request-body:
type: object
description: Payload for creating a new slash command.
required:
- name
- hint
- scope
properties:
execution_type:
type: string
enum:
- deluge
- webhook
description: |
Defines how the command executes its handlers.
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.
example: deluge
execution_url:
type: string
maxLength: 225
description: |
The URL that Zoho Cliq will POST handler events to when the command is invoked.
Required when execution_type is webhook.
Maximum length: 225 characters.
example: https://api.yourcompany.com/cliq/commands/handler
name:
type: string
maxLength: 30
description: |
Name of the slash command. This is the text that users will type after the "/" to invoke the command. Must be unique within the command's scope.
Maximum length: 30 characters
Allowed characters: Only lowercase letters.
hint:
type: string
maxLength: 128
description: |
Hint shown in the slash command picker to help users understand the command's purpose. Should be concise and descriptive.
Maximum length: 128 characters
description:
type: string
maxLength: 300
description: |
Detailed description of the slash command's functionality. This can provide more in-depth information than the hint and may be shown in command documentation or tooltips.
Maximum length: 300 characters
options:
type: object
description: |
Options are additional properties which can alter the output of a /command based on the user's requirements.
Maximum size: 5 key-value pairs.
- Key: Option name - identifies the option (e.g.
location, unit).
- Value: Option description - explains what the option does (e.g.
"City to check weather for").
Example syntax:
{"options": {"location": "City to check weather for", "unit": "Temperature unit: celsius or fahrenheit"}}
additionalProperties:
type: string
maxLength: 100
scope:
type: string
enum:
- organization
- team
- personal
description: |
Access scope of the slash command. Determines who can see and use the command.
Allowed values:
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.
team_ids:
type: array
maxItems: 4
description: |
List of team_ids that are allowed to access the command when scope is set to team. Each ID corresponds to a team within the organization.
Maximum items: 4 team IDs can be specified.
This field is required if 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.
Image requirements:
- Format: PNG or JPEG
- Maximum size: 100 KB
- Recommended dimensions: 64x64 pixels for optimal display
max_suggestions:
type: integer
maximum: 5
description: |
Maximum number of autocomplete suggestions that can be selected by the user when the command is typed.
Maximum value: 5 suggestions
example:
name: greet
hint: Send a greeting message
description: Sends a customizable greeting to a user or channel
scope: organization
options:
user: The user to greet
msg: Custom greeting message
max_suggestions: 5
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)
base64_regex:
type: string
description: Base64-encoded pagination or sync token used for cursor-based pagination and incremental data sync.
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: ''
scopes:
Commands.UPDATE: Update slash command configurations and manage command handlers.
Commands.READ: Read slash command configurations, handlers, and execution logs.
Commands.DELETE: Permanently delete slash commands and their handlers.
Commands.CREATE: Create new custom Slash Commands.