openapi: 3.0.0
info:
title: Functions
version: '3.0'
description: |
Functions are reusable, UI-triggered components in Zoho Cliq that execute when a user interacts with a UI element - clicking a button in a message, submitting or changing a form, or clicking a button inside a widget. Unlike commands or message actions which are user-text-driven, functions are driven by structured UI interactions.
For more information, refer to the Functions Help Documentation.
Function Types
The function_type field determines which UI trigger activates the function:
| function_type |
Trigger |
button |
Triggered when a user clicks a button inside a chat message. |
form |
Triggered by form interactions - view (render), field change, dynamic select, and submit events. |
widget_button |
Triggered when a user clicks a button rendered inside a Cliq widget. |
Function Handlers
Each function supports one or more handlers based on its type. Handlers define the logic executed at each stage of the UI interaction:
| Handler |
Applicable function_type |
Description |
button_handler |
button |
Executes when a button in a message is clicked. |
form_view_handler |
form |
Renders the form UI when a user navigates to the form's permalink URL. |
form_submit_handler |
form |
Executes when the user submits the form. |
form_change_handler |
form |
Executes when a field value changes within the form. |
form_dynamic_select_handler |
form |
Populates dynamic dropdown options within a form field. |
widget_button_handler |
widget_button |
Executes when a button inside a Cliq widget is clicked. |
What can you do with the Functions API?
With the Functions API, you can programmatically create and manage functions, configure their handlers (Deluge scripts or webhook permissions), update function configurations, and retrieve function details - all without using the Cliq Developer console.
Each function has an execution_type that defines how handlers run when a UI element is triggered. The Functions API supports two execution types:
Deluge Functions (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, it defaults to deluge.
- Handler logic is defined using the
script field when creating or updating handlers.
- Suitable for teams building UI-driven automations entirely within the Zoho platform.
Webhook Functions
When a UI element is interacted with, Zoho Cliq sends an HTTP POST request to your execution_url. Your server processes the event and returns a response that Cliq renders back to the user.
- To create a Webhook function, set
execution_type to webhook and provide the execution_url.
- Handler permissions (
chat, message, user) control which data attributes are included in the webhook payload. Note: location and attachments are not available for function handlers.
- Ideal for functions that need to integrate with external systems or require custom server-side processing.
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: Functions
description: Functions Module
paths:
/functions:
post:
summary: Create a new function
operationId: create_a_new_function
description: |
Create a new Function in the Cliq platform. Functions are reusable UI-triggered components that execute when a user clicks a button, submits a form, or interacts with a widget button. The function_type determines the UI trigger.
Functions support two execution types:
- Deluge (default): Handler logic runs on Zoho's platform via Deluge scripts. Best for UI interactions within the Zoho ecosystem - approvals, form submissions, inline actions.
- Webhook: When a UI element is interacted with, Cliq sends a POST request to your
execution_url. Your server processes the event and returns a response that Cliq renders back to the user. Supports chat, message, and user permissions.
Pass execution_type: "webhook" and a valid execution_url to create a Webhook function. 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 |
| function_creation_limit_exceeded |
Organization has reached the maximum number of functions. |
| function_name_already_exists |
A function with this name already exists. |
| invalid_inputs |
Request body validation failed. |
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 function. Provide `name`, `description`, and `function_type`. Set `execution_type` to `webhook` and include `execution_url` for a Webhook function.
required: true
content:
application/json:
examples:
button_function_deluge:
summary: Deluge button function
value:
name: ApproveRequest
description: Handles approval button clicks in messages
function_type: button
execution_type: deluge
button_function_webhook:
summary: Webhook button function
value:
name: ApproveExpense
description: Forwards approval clicks to external HR system
function_type: button
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/functions/handler
form_function:
summary: Form function
value:
name: SubmitFeedback
description: Processes feedback form submissions from users
function_type: form
widget_button_function:
summary: Widget button function
value:
name: RefreshWidget
description: Handles button clicks inside widgets
function_type: widget_button
schema:
$ref: '#/components/schemas/v3-function-create'
responses:
'200':
description: Function created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionResponse'
examples:
button_function_deluge:
summary: Deluge button function response
value:
url: /api/v3/functions
type: function
data:
name: ApproveRequest
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Handles approval button clicks in messages
scope: personal
button_function_webhook:
summary: Webhook button function response
value:
url: /api/v3/functions
type: function
data:
name: ApproveExpense
id: '53719000002124014'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/functions/handler
status: enabled
type: custom
description: Forwards approval clicks to external HR system
scope: personal
form_function:
summary: Form function response
value:
url: /api/v3/functions
type: function
data:
name: SubmitFeedback
id: '53719000002124012'
function_type: form
handlers:
- type: form_submit_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Processes feedback form submissions from users
scope: personal
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Functions.CREATE
tags:
- Functions
get:
summary: List all functions
operationId: list_all_functions
description: |
Retrieve a paginated list of all functions defined by the authenicated user.
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:
- name: next_token
in: query
description: Token for fetching the next page of results. Omit this parameter to retrieve the first page.
required: false
schema:
type: string
- name: sync_token
in: query
description: Token for incremental synchronization. Provide the sync_token value from a previous response to retrieve only functions that were created or updated since that response was generated.
required: false
schema:
type: string
- name: limit
in: query
description: |
Maximum number of functions to return per page.
Default: 20
Maximum: 50
required: false
schema:
type: integer
default: 20
maximum: 50
responses:
'200':
description: List of functions returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionListResponse'
example:
url: /api/v3/functions
next_token: NTB8LTF8NTM3MTkwMDAwMDAyNDUwMTE=
type: function
sync_token: NTB8MTc3NzQzMjg2NjI1MXw1MzcxOTAwMDAwMjEyNDAxMQ==
data:
- name: createTask
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Creates a task in integrated system
scope: personal
- name: SubmitFeedback
id: '53719000002124012'
function_type: form
handlers:
- type: form_submit_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Processes feedback form submissions from users
scope: personal
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Functions.READ
tags:
- Functions
/functions/{FUNCTION_ID}:
patch:
summary: Update an existing function
operationId: update_an_existing_function
description: |
Update the configuration (name and description) of an existing function.
To modify the function's handler logic, use the handler-level endpoints.
For Webhook functions, you can also update the execution_url independently at any time to redirect all handler events to a new server endpoint.
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 |
| function_not_found |
Function with the specified ID was not found. |
| function_name_already_exists |
Another function with this name already exists. |
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: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
requestBody:
description: Updates function metadata. For Webhook functions, use `execution_url` to update the server endpoint.
required: true
content:
application/json:
examples:
update_details:
summary: Update function details
value:
name: createTaskUpdated
description: Updated function description
update_webhook_url:
summary: Update webhook execution URL
value:
execution_url: https://api.yourcompany.com/cliq/functions/updated-handler
schema:
$ref: '#/components/schemas/v3-function-edit'
responses:
'200':
description: Function updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionResponse'
examples:
update_details:
summary: Deluge function updated
value:
url: /api/v3/functions/53719000002124011
type: function
data:
name: createTaskUpdated
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Updated function description
scope: personal
update_webhook_url:
summary: Webhook function execution URL updated
value:
url: /api/v3/functions/53719000002124014
type: function
data:
name: ApproveExpense
id: '53719000002124014'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/functions/updated-handler
status: enabled
type: custom
description: Forwards approval clicks to external HR system
scope: personal
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Functions.UPDATE
tags:
- Functions
get:
summary: Get details of a specific function
operationId: get_details_of_a_specific_func
description: |
Retrieve the full configuration of a single Function identified by its `FUNCTION_ID`. The response includes the function name, description, and a summary of the configured handlers.
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 |
| function_not_found |
Function 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: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
responses:
'200':
description: Function details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionResponse'
example:
url: /api/v3/functions/53719000002124011
type: function
data:
name: createTask
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Creates a task in integrated system
scope: personal
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Functions.READ
tags:
- Functions
delete:
summary: Delete a specific function
operationId: delete_a_specific_function
description: |
Permanently delete a Function and all its associated handlers. Any platform component that calls this function will stop working once it is deleted. 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 |
| function_not_found |
Function 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: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
responses:
'204':
description: No Content. Function 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.Functions.DELETE
tags:
- Functions
/functions/{FUNCTION_ID}/handlers:
post:
summary: Create a handler for a specific function
operationId: createFunctionHandler
description: |
Create a handler for a function. Handlers define the logic that executes when a user triggers the UI element (button click, form submit, widget interaction, etc.).
The field you provide depends on the function's execution type:
- Deluge function: Provide the
script field with the Deluge source code to execute when the handler fires.
- Webhook function: Provide the
permissions field - an array of data attributes your server needs to receive in the webhook payload. Do not pass script for Webhook functions.
Permissions availability by handler type
| Handler |
chat |
message |
user |
button_handler |
✓ |
✓ |
✓ |
form_submit_handler |
✓ |
✓ |
✓ |
form_change_handler |
✓ |
- |
✓ |
form_dynamic_select_handler |
✓ |
- |
✓ |
form_view_handler |
- |
- |
✓ |
widget_button_handler |
- |
- |
✓ |
Note: attachments and location are not available for any function handler type. Only chat, message, and user are applicable.
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 (e.g., name for menu_handler). |
| 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: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
requestBody:
description: Creates a function handler. For Deluge functions, provide `type` and `script`. For Webhook functions, provide `type` and `permissions`.
required: true
content:
application/json:
examples:
button_handler_deluge:
summary: Button handler - Deluge
value:
type: button_handler
script: |-
response = Map();
response.put("text", "Button clicked!");
return response;
button_handler_webhook:
summary: Button handler - Webhook
value:
type: button_handler
permissions:
- chat
- message
- user
form_submit_handler_deluge:
summary: Form submit handler - Deluge
value:
type: form_submit_handler
script: |-
values = form.values;
info values;
return {"type": "banner", "text": "Form submitted!", "status": "success"};
form_submit_handler_webhook:
summary: Form submit handler - Webhook
value:
type: form_submit_handler
permissions:
- chat
- user
form_view_handler:
summary: Form view handler - Deluge
value:
type: form_view_handler
script: |-
form = Map();
form.put("title", "Feedback Form");
actions = Map();
submit = Map();
submit.put("type", "invoke.function");
actions.put("submit", submit);
form.put("actions", actions);
return form;
schema:
$ref: '#/components/schemas/v3-exehandler-create'
responses:
'200':
description: Function handler created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionHandlerResponse'
examples:
button_handler_deluge:
summary: Button handler created - Deluge
value:
url: /api/v3/functions
type: function
data:
name: ApproveRequest
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Creates a task in integrated system
scope: personal
button_handler_webhook:
summary: Button handler created - Webhook
value:
url: /api/v3/functions
type: function
data:
name: ApproveExpense
id: '53719000002124014'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: webhook
execution_url: https://api.yourcompany.com/cliq/functions/handler
status: enabled
type: custom
description: Forwards approval clicks to external HR system
scope: personal
form_submit_handler_deluge:
summary: Form submit handler created - Deluge
value:
url: /api/v3/functions
type: function
data:
name: SubmitFeedback
id: '53719000002124012'
function_type: form
handlers:
- type: form_submit_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Processes feedback form submissions from users
scope: personal
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Functions.UPDATE
tags:
- Functions
/functions/{FUNCTION_ID}/handlers/{FUNCTION_HANDLER_TYPE}:
patch:
summary: Update a handler for a specific function
operationId: updateFunctionHandler
description: |
Update a handler for a specific function. What you provide depends on the function's execution type:
- Deluge function: Update the
script attribute with the revised Deluge source code to execute when the handler fires.
- Webhook function: Update the
permissions array to change which data attributes (chat, message, user) are forwarded to your server. Note: attachments and location are not available for function handlers.
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/FUNCTION_HANDLER_TYPE_regex'
example: FUNCTION_HANDLER_TYPE
in: path
name: FUNCTION_HANDLER_TYPE
description: |
Type of the function handler to update. Supported handler types are:
button_handler - for button functionsform_submit_handler - for form functions, triggered on form submissionform_change_handler - for form functions, triggered on form field value changeform_view_handler - for form functions, triggered when the form is renderedform_dynamic_select_handler - for form functions, triggered when a dynamic select field is loadedwidget_button_handler - for widget functions, triggered on widget button click
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
requestBody:
description: Updates a function handler. For Deluge functions, provide `script`. For Webhook functions, provide `permissions`.
required: true
content:
application/json:
examples:
update_script_deluge_button:
summary: Update script - Deluge button handler
value:
script: |-
response = Map();
response.put("text", "Task approved successfully!");
return response;
update_permissions_webhook_button:
summary: Update permissions - Webhook button handler
value:
permissions:
- chat
- message
- user
update_script_form_submit:
summary: Update script - Form submit handler
value:
script: |-
values = form.get("values");
task_name = values.get("task_name");
response = Map();
response.put("type", "banner");
response.put("text", "Task '" + task_name + "' created.");
response.put("status", "success");
return response;
update_permissions_webhook_form:
summary: Update permissions - Webhook form handler
value:
permissions:
- chat
- user
form_change_handler:
summary: Update script - Form change handler
value:
script: |-
changed_field = form.get("changed_field");
form_response = Map();
if(changed_field == "priority") {
priority_val = form.get("values").get("priority");
options = List();
if(priority_val == "high") {
options.add("Escalate");
options.add("Notify Manager");
} else {
options.add("Standard Process");
}
form_response.put("action_field", Map());
}
return form_response;
form_view_handler:
summary: Update script - Form view handler
value:
script: |-
form = Map();
form.put("title", "Create Task");
fields = List();
task_field = Map();
task_field.put("name", "task_name");
task_field.put("label", "Task Name");
task_field.put("type", "text");
task_field.put("mandatory", true);
fields.add(task_field);
due_field = Map();
due_field.put("name", "due_date");
due_field.put("label", "Due Date");
due_field.put("type", "date");
fields.add(due_field);
form.put("fields", fields);
actions = Map();
submit = Map();
submit.put("type", "invoke.function");
actions.put("submit", submit);
form.put("actions", actions);
return form;
widget_button_handler:
summary: Update script - Widget button handler
value:
script: |-
button_name = action.get("name");
widget = Map();
widget.put("type", "zhtml");
widget.put("body", "Button '" + button_name + "' clicked. Widget refreshed at " + zoho.currenttime + "
");
return widget;
schema:
$ref: '#/components/schemas/v3-exehandler-edit'
responses:
'200':
description: Function handler updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionHandlerResponse'
examples:
update_script_deluge:
summary: Script updated - Deluge function
value:
url: /api/v3/functions/53719000002124011/handlers/button_handler
type: execution_handler
data:
name: button_handler
script: |-
response = Map();
response.put("text", "Task approved successfully!");
return response;
function_id: '53719000002124011'
update_permissions_webhook:
summary: Permissions updated - Webhook function
value:
url: /api/v3/functions/53719000002124014/handlers/button_handler
type: execution_handler
data:
name: button_handler
permissions:
- chat
- message
- user
function_id: '53719000002124014'
form_submit_handler:
summary: Form submit handler response
value:
url: /api/v3/functions/53719000002124012/handlers/form_submit_handler
type: execution_handler
data:
name: form_submit_handler
script: |-
values = form.get("values");
task_name = values.get("task_name");
due_date = values.get("due_date");
response = Map();
response.put("type", "banner");
response.put("text", "Task '" + task_name + "' created with due date: " + due_date);
response.put("status", "success");
return response;
function_id: '53719000002124012'
form_change_handler:
summary: Form change handler response
value:
url: /api/v3/functions/53719000002124012/handlers/form_change_handler
type: execution_handler
data:
name: form_change_handler
script: |-
changed_field = form.get("changed_field");
form_response = Map();
if(changed_field == "priority") {
priority_val = form.get("values").get("priority");
options = List();
if(priority_val == "high") {
options.add("Escalate");
options.add("Notify Manager");
} else {
options.add("Standard Process");
}
form_response.put("action_field", Map());
}
return form_response;
function_id: '53719000002124012'
form_view_handler:
summary: Form view handler response
value:
url: /api/v3/functions/53719000002124012/handlers/form_view_handler
type: execution_handler
data:
name: form_view_handler
script: |-
form = Map();
form.put("title", "Create Task");
fields = List();
task_field = Map();
task_field.put("name", "task_name");
task_field.put("label", "Task Name");
task_field.put("type", "text");
task_field.put("mandatory", true);
fields.add(task_field);
due_field = Map();
due_field.put("name", "due_date");
due_field.put("label", "Due Date");
due_field.put("type", "date");
fields.add(due_field);
form.put("fields", fields);
actions = Map();
submit = Map();
submit.put("type", "invoke.function");
actions.put("submit", submit);
form.put("actions", actions);
return form;
function_id: '53719000002124012'
widget_button_handler:
summary: Widget button handler response
value:
url: /api/v3/functions/53719000002124013/handlers/widget_button_handler
type: execution_handler
data:
name: widget_button_handler
script: |-
button_name = action.get("name");
widget = Map();
widget.put("type", "zhtml");
widget.put("body", "Button '" + button_name + "' clicked. Widget refreshed at " + zoho.currenttime + "
");
return widget;
function_id: '53719000002124013'
'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.Functions.UPDATE
tags:
- Functions
get:
summary: Get details of a specific function handler
operationId: getFunctionHandler
description: |
Retrieve the configuration and deluge source code of a function 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_get_failed |
Failed to fetch the execution handler. |
| execution_handler_not_found |
Specified handler was not found for this function. |
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/FUNCTION_HANDLER_TYPE_regex'
example: FUNCTION_HANDLER_TYPE
in: path
name: FUNCTION_HANDLER_TYPE
description: |
Name of the function execution handler. For functions with multiple handlers, this parameter is required to specify which handler's details to retrieve.
Allowed values:
button_handler: Handler for button click events.form_submit_handler: Handler for form submission events.form_view_handler: Handler for rendering form views.form_change_handler: Handler for form field change events.form_dynamic_select_handler: Handler for dynamic select field load events.widget_button_handler: Handler for widget button click events.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
responses:
'200':
description: Function handler details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FunctionHandlerDetailsResponse'
'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.Functions.READ
tags:
- Functions
delete:
summary: Delete a handler from a specific function
operationId: deleteFunctionHandler
description: |
Permanently remove a named execution handler from a Function. Once deleted, the handler's Deluge code is lost and the function will no longer be executable until a new handler is added.
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 execution handler. |
| default_handler_delete_not_allowed |
Default handlers cannot be deleted. |
| execution_handler_not_found |
Specified handler was not found for this function. |
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/FUNCTION_HANDLER_TYPE_regex'
example: FUNCTION_HANDLER_TYPE
in: path
name: FUNCTION_HANDLER_TYPE
description: |
Name of the function execution handler. For functions with multiple handlers, this parameter is required to specify which handler to delete.
Allowed values:
button_handler: Handler for button click events.form_submit_handler: Handler for form submission events.form_view_handler: Handler for rendering form views.form_change_handler: Handler for form field change events.form_dynamic_select_handler: Handler for dynamic select field load events.widget_button_handler: Handler for widget button click events.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: FUNCTION_ID
in: path
name: FUNCTION_ID
description: Unique numeric identifier of the function. To learn how to retrieve this ID, see FUNCTION_ID in the Glossary page.
required: true
responses:
'200':
description: Function handler deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NoResponse'
'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.Functions.UPDATE
tags:
- Functions
components:
schemas:
NoResponse:
type: object
description: Represents an empty successful response where no payload is returned.
properties:
Response Code:
type: string
example: 204 No response
FunctionResponse:
type: object
description: Response schema for function create, get, and update operations.
properties:
url:
type: string
description: API endpoint URL for the function resource.
example: /api/v3/functions
type:
type: string
description: Resource type.
example: function
data:
type: object
description: Function details.
properties:
name:
type: string
example: createTask
id:
type: string
example: '53719000002124011'
function_type:
type: string
example: button
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
status:
type: string
example: enabled
type:
type: string
example: custom
description:
type: string
scope:
type: string
example: personal
example:
url: /api/v3/functions
type: function
data:
name: createTask
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Creates a task in integrated system
scope: personal
GenericResponse:
type: object
description: Generic API response envelope.
properties:
url:
type: string
example: /api/v3/resource
type:
type: string
example: object
data:
type: object
additionalProperties: true
FunctionListResponse:
type: object
description: Response schema for listing functions.
properties:
deleted:
type: array
items:
type: string
url:
type: string
example: /api/v3/functions
next_token:
type: string
type:
type: string
example: function
total_count:
type: integer
sync_token:
type: string
data:
type: array
items:
type: object
additionalProperties: true
example:
url: /api/v3/functions
next_token: NTB8LTF8NTM3MTkwMDAwMDAyNDUwMTE=
type: function
sync_token: NTB8MTc3NzQzMjg2NjI1MXw1MzcxOTAwMDAwMjEyNDAxMQ==
data:
- name: createTask
id: '53719000002124011'
function_type: button
handlers:
- type: button_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Creates a task in integrated system
scope: personal
- name: SubmitFeedback
id: '53719000002124012'
function_type: form
handlers:
- type: form_submit_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
description: Processes feedback form submissions from users
scope: personal
FunctionHandlerDetailsResponse:
type: object
description: Response schema returned when fetching the full details of a specific function handler.
properties:
url:
type: string
description: Endpoint URL of the handler resource.
type:
type: string
description: Resource type identifier.
example: button_handler
data:
type: object
description: Full configuration and runtime parameter details of the handler.
properties:
script:
type: string
description: Deluge source code of the handler.
return_type:
type: string
description: Return type expected from the handler script.
example: MAP
params:
type: array
description: List of runtime parameters passed to the handler script.
items:
type: object
properties:
param_name:
type: string
description: Name of the parameter.
param_type:
type: string
description: Data type of the parameter (e.g., MAP, STRING, BOOLEAN).
additionalProperties: true
example:
url: /api/v3/functions/53719000002124011/handlers/button_handler
type: button_handler
data:
script: |-
// Triggered when a user clicks the "Approve Task" instant button
// [Approve Task](invoke.function|ApproveTask)
response = Map();
task_name = arguments.get("task_name");
assignee = arguments.get("assignee");
response.put("text", "✅ Task '" + task_name + "' has been approved and assigned to " + assignee + ". They'll be notified shortly.");
return response;
return_type: MAP
params:
- param_name: access
param_type: MAP
- param_name: environment
param_type: MAP
- param_name: chat
param_type: MAP
- param_name: user
param_type: MAP
- param_name: message
param_type: MAP
- param_name: target
param_type: MAP
- param_name: arguments
param_type: MAP
- param_name: event
param_type: STRING
- param_name: location
param_type: MAP
FunctionHandlerResponse:
type: object
description: Response schema for function handler operations.
properties:
url:
type: string
example: /api/v3/functions/53719000002124011/handlers/button_handler
type:
type: string
example: execution_handler
data:
type: object
properties:
name:
type: string
example: button_handler
script:
type: string
example: |-
response = Map();
response.put("text", "Task approved successfully!");
return response;
function_id:
type: string
example: '53719000002124011'
example:
url: /api/v3/functions/53719000002124011/handlers/button_handler
type: execution_handler
data:
name: button_handler
script: |-
response = Map();
response.put("text", "Task approved successfully!");
return response;
function_id: '53719000002124011'
v3-function-create:
type: object
description: Payload for creating a new function.
required:
- name
- description
- function_type
properties:
name:
type: string
maxLength: 30
description: |
Unique name for the function.
Maximum length: 30 characters.
description:
type: string
maxLength: 300
description: |
Description for the function.
Maximum length: 300 characters.
function_type:
type: string
enum:
- button
- form
- widget_button
description: |
Type of the function which determines where it can be invoked from.
Allowed values:
- button - Triggered by button clicks in messages.
- form - Triggered by form submissions and interactions.
- widget_button - Triggered by button clicks inside widgets.
Note: function_type cannot be changed after creation.
execution_type:
type: string
enum:
- deluge
- webhook
description: |
Execution type of the function.
- deluge (default) - Handler logic is written in Deluge and executed on Zoho's platform.
- webhook - Cliq sends a POST request to your
execution_url when the function is triggered. Provide execution_url when using this type.
execution_url:
type: string
maxLength: 225
description: |
The URL that Cliq sends a POST request to when the function is triggered. Required when execution_type is webhook.
Maximum length: 225 characters.
base64_regex:
type: string
description: Base64-encoded pagination or sync token used for cursor-based pagination and incremental data sync.
v3-function-edit:
type: object
description: Payload for updating a function. `function_type` cannot be changed after creation.
properties:
name:
type: string
maxLength: 30
description: |
Updated function name.
Maximum length: 30 characters.
example: createTask
description:
type: string
maxLength: 300
description: |
Updated function description.
Maximum length: 300 characters.
example: Creates a task in integrated system
execution_url:
type: string
maxLength: 225
description: |
Updated webhook execution URL for the function. Only applicable when the function's execution_type is webhook.
Maximum length: 225 characters.
FUNCTION_ID:
type: string
description: Unique numeric identifier of a Function. Used in function management and handler endpoints.
longid_regex:
type: string
description: Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions.
v3-exehandler-edit:
type: object
description: Payload for updating an existing function handler.
properties:
script:
type: string
description: Updated Deluge script source code for the handler. Maximum size is 250KB. Only applicable for Deluge functions.
permissions:
type: array
maxItems: 5
description: |
List of data attributes to include in the webhook payload. Only applicable for Webhook functions. Not all permissions are valid for every handler type - refer to the Create a handler table for availability.
Available values: chat, message, user.
items:
type: string
enum:
- chat
- message
- user
FUNCTION_HANDLER_TYPE_regex:
type: string
description: Name of a function handler.
enum:
- button_handler
- form_submit_handler
- form_change_handler
- form_dynamic_select_handler
- form_view_handler
- widget_button_handler
v3-exehandler-create:
type: object
description: Payload for creating a new function handler.
required:
- type
properties:
type:
type: string
enum:
- button_handler
- form_submit_handler
- form_change_handler
- form_dynamic_select_handler
- form_view_handler
- widget_button_handler
description: |
Type of the function handler which determines the trigger for execution.
Allowed values:
- button_handler - Triggered by button clicks in messages.
- form_submit_handler - Triggered by form submissions.
- form_change_handler - Triggered by changes in form fields.
- form_dynamic_select_handler - Triggered to populate dynamic field options in forms.
- form_view_handler - Renders the form UI when a user navigates to the form's permalink URL.
- widget_button_handler - Triggered by button clicks inside widgets.
script:
type: string
description: |
Deluge script source code for the handler. Maximum size is 250KB. Only applicable for Deluge functions.
permissions:
type: array
maxItems: 5
description: |
List of data attributes to include in the webhook payload when the handler fires. Only applicable for Webhook functions. Not all permissions are valid for every handler type - refer to the Create a handler table for availability.
Available values: chat, message, user.
items:
type: string
enum:
- chat
- message
- user
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: ''
scopes:
ZohoCliq.Functions.CREATE: Create new Functions in the platform.
ZohoCliq.Functions.READ: Read function configurations, handlers, and execution logs.
ZohoCliq.Functions.UPDATE: Update function configurations and manage function handlers.
ZohoCliq.Functions.DELETE: Permanently delete Functions and their handlers.