Message Actions are custom contextual actions that appear in the right-click (or long-press on mobile) context menu of individual chat messages. When a user selects an action, the configured handler executes with the selected message as its input - enabling workflows like ticket creation, message translation, content archiving, and more, directly from within a conversation.
For more information, refer to the Message Actions Help Documentation.
Key Concepts
text, link, or attachment.true, allows the action to be applied to multiple selected messages at once.Action Scope
| Scope | Visibility |
|---|---|
organization |
Available to all users in the organization. |
team |
Restricted to members of the specified teams. |
personal |
Visible only to the creator. |
What can you do with the Message Actions API?
With the Message Actions API, you can programmatically create and manage message actions, configure their execution handlers, control scope and message type filters, and retrieve action details - all without using the Cliq Developer console.
Each message action has an execution_type that determines how its handler runs when triggered. The Message Actions API supports two execution types:
Deluge Message Actions (default)
Handler logic is written in Deluge and runs entirely within Zoho's platform. The script receives full message context as input.
execution_type is not specified, it defaults to deluge.script field when creating or updating the execution_handler.Webhook Message Actions
When a user triggers the action, Zoho Cliq sends an HTTP POST request to your execution_url containing the event payload. Your server processes it and returns a response that Cliq acts upon.
execution_type to webhook and provide the execution_url.attachments, chat, location, message, user) control which data attributes are included in the webhook payload sent to your server.Create a new Message Action. Message actions appear in the right-click / long-press context menu for individual chat messages. When a user selects the action, the configured handler executes with the selected message as input.
Message Actions support two execution types:
execution_url with the event payload. Your server processes it and returns the response. Supports all 5 permissions (attachments, chat, location, message, user).
Pass execution_type: "webhook" and a valid execution_url to create a Webhook message action. If execution_type is omitted, it defaults to deluge.
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.
| Error Code | Description |
|---|---|
| msgaction_creation_limit_exceeded | Organization has reached the maximum number of message actions. |
| msgaction_name_already_exists | A message action with this name already exists. |
| invalid_inputs | Request body validation failed. |
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.
sync_token value from the previous response. For the initial request, omit this parameter or set it to null to retrieve all message actions.
required: false
- schema:
description: ''
type: integer
in: query
name: limit
description: |
Maximum number of message actions to return per page.next_token, use its value in this parameter to retrieve the next page. Omit this parameter or set it to null if there are no more pages to fetch.
required: false
responses:
'200':
description: List of message actions returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageActionListItemsResponse'
example:
url: /api/v3/messageactions
type: messageaction
sync_token: NTB8MTc3NzQzMjI3NjY1OHw1MzcxOTAwMDAwMjEyNDAxMA==
data:
- multi_selectable: true
name: Create Ticket
id: '53719000002124010'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Create a helpdesk ticket
status: enabled
type: custom
message_types:
- text
- link
scope: organization
- multi_selectable: false
name: Translate
id: '53719000002124013'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Translate selected message to English
status: enabled
type: custom
message_types:
- text
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.MessageActions.READ
tags:
- messageactions
/messageactions/{MESSAGE_ACTION_ID}:
patch:
summary: Update an existing message action
operationId: update_an_existing_message_act
description: |
Update the configuration of an existing message action.
All fields are optional. Only the fields you provide will be updated; omitted fields remain unchanged.
For Webhook message actions, you can update the execution_url independently at any time to redirect the action 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.
| Error Code | Description |
|---|---|
| msgaction_not_found | Message action with the specified ID was not found. |
| msgaction_name_already_exists | Another message action with this name already exists. |
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.
| Error Code | Description |
|---|---|
| msgaction_not_found | Message action with the specified ID was not found. |
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.
| Error Code | Description |
|---|---|
| msgaction_not_found | Message action with the specified ID was not found. |
script attribute with the revised Deluge source code to execute when the action fires.permissions array to change which data attributes are forwarded to your server. All 5 permissions are available for message action 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.
| Error Code | Description |
|---|---|
| execution_handler_update_failed | Failed to update the execution handler. |
| execution_handler_not_found | Specified handler was not found for this message action. |
execution_handler, which is triggered when the message action is invoked.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: MESSAGE_ACTION_ID
in: path
name: MESSAGE_ACTION_ID
description: Unique numeric identifier of the message action. To learn how to retrieve this ID, see MESSAGE_ACTION_ID in the Glossary page.
required: true
requestBody:
description: Updates a message-action handler. For Deluge actions, provide `script`. For Webhook actions, provide `permissions`.
required: true
content:
application/json:
examples:
update_script_deluge:
summary: Update script - Deluge message action
value:
script: |
response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
update_permissions_webhook:
summary: Update permissions - Webhook message action
value:
permissions:
- chat
- message
- user
- attachments
schema:
$ref: '#/components/schemas/v3-exehandler-edit'
responses:
'200':
description: Message action handler updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/updateMessageActionHandlerResponse'
examples:
update_script_deluge:
summary: Script updated - Deluge message action
value:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
function_id: '53719000002124010'
update_permissions_webhook:
summary: Permissions updated - Webhook message action
value:
url: /api/v3/messageactions/53719000002124011/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
permissions:
- chat
- message
- user
- attachments
function_id: '53719000002124011'
'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.MessageActions.UPDATE
tags:
- messageactions
get:
summary: Get details of a specific message action handler
operationId: getMessageActionHandler
description: |
Retrieve the configuration and Deluge source code of the execution handler attached to a specific Message Action.
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.
| Error Code | Description |
|---|---|
| execution_handler_get_failed | Failed to fetch the execution handler. |
| execution_handler_not_found | Specified handler was not found for this message action. |
execution_handler, which is triggered when the message action is invoked.
required: true
- schema:
description: ''
$ref: '#/components/schemas/longid_regex'
example: MESSAGE_ACTION_ID
in: path
name: MESSAGE_ACTION_ID
description: Unique numeric identifier of the message action. To learn how to retrieve this ID, see MESSAGE_ACTION_ID in the Glossary page.
required: true
responses:
'200':
description: Message action handler details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageActionHandlerResponse'
example:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
function_id: '53719000002124010'
'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.MessageActions.READ
tags:
- messageactions
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
MessageActionResponse:
type: object
description: Response schema for message action create, get, and update operations.
properties:
url:
type: string
description: API endpoint URL for the message action resource.
example: /api/v3/messageactions
type:
type: string
description: Resource type.
example: messageaction
data:
type: object
description: Message action details.
properties:
multi_selectable:
type: boolean
example: true
name:
type: string
example: Create Ticket
id:
type: string
example: '53719000002124010'
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
example: Create a helpdesk ticket
status:
type: string
example: enabled
type:
type: string
example: custom
message_types:
type: array
items:
type: string
scope:
type: string
example: organization
example:
url: /api/v3/messageactions
type: messageaction
data:
multi_selectable: true
name: Create Ticket
id: '53719000002124010'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Create a helpdesk ticket
status: enabled
type: custom
message_types:
- text
- link
scope: organization
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
updateMessageActionHandlerResponse:
type: object
description: Response schema for message action handler update operations.
properties:
url:
type: string
description: API endpoint URL for the handler resource.
type:
type: string
description: Handler type.
example: execution_handler
data:
type: object
additionalProperties: true
properties:
name:
type: string
description: Handler name.
script:
type: string
description: Updated Deluge script source code.
function_id:
type: string
description: Unique identifier of the underlying function associated with this handler.
example:
url: /api/v3/messageactions/53719000002124010/handlers/execution_handler
type: execution_handler
data:
name: execution_handler
script: |
response = Map();
message = info.get("message").get("text");
response.put("text", "Ticket created for: " + message);
return response;
function_id: '53719000002124010'
MessageActionUpdateResponse:
type: object
description: Response schema for message action update operations.
properties:
url:
type: string
description: API endpoint URL for the updated message action resource.
example: /api/v3/messageactions/53719000002124010
type:
type: string
description: Resource type.
example: messageaction
data:
type: object
description: Updated message action details.
properties:
name:
type: string
id:
type: string
hint:
type: string
scope:
type: string
multi_selectable:
type: boolean
message_types:
type: array
items:
type: string
team_ids:
type: array
items:
type: integer
handlers:
type: array
creator:
type: object
execution_type:
type: string
status:
type: string
type:
type: string
example:
url: /api/v3/messageactions/53719000002124010
type: messageaction
data:
name: Create Ticket
id: '53719000002124010'
hint: Convert this message into a support ticket
scope: organization
multi_selectable: false
message_types:
- text
- link
- attachment
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
status: enabled
type: custom
MessageActionListItemsResponse:
type: object
description: Response schema for listing message actions.
properties:
url:
type: string
example: /api/v3/messageactions
type:
type: string
example: messageaction
sync_token:
type: string
description: Token for incremental sync. Pass this in the next request to retrieve only message actions updated since this response.
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
hint:
type: string
scope:
type: string
multi_selectable:
type: boolean
message_types:
type: array
items:
type: string
handlers:
type: array
creator:
type: object
execution_type:
type: string
status:
type: string
type:
type: string
example:
url: /api/v3/messageactions
type: messageaction
sync_token: NTB8MTc3NzQzMjI3NjY1OHw1MzcxOTAwMDAwMjEyNDAxMA==
data:
- multi_selectable: true
name: Create Ticket
id: '53719000002124010'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Create a helpdesk ticket
status: enabled
type: custom
message_types:
- text
- link
scope: organization
- multi_selectable: false
name: Translate
id: '53719000002124013'
handlers:
- type: execution_handler
creator:
name: James
id: '65113112'
execution_type: deluge
hint: Translate selected message to English
status: enabled
type: custom
message_types:
- text
scope: personal
MessageActionListResponse:
type: object
description: Response schema for listing message actions.
properties:
deleted:
type: array
items:
type: string
url:
type: string
example: /api/v3/messageactions
next_token:
type: string
type:
type: string
example: messageaction
total_count:
type: integer
sync_token:
type: string
data:
type: array
items:
type: object
additionalProperties: true
MessageActionHandlerResponse:
type: object
description: Response schema for message action handler operations.
properties:
url:
type: string
type:
type: string
example: execution_handler
data:
type: object
additionalProperties: true
HANDLER_TYPE_regex:
type: string
description: Type of the message action handler. Message actions support only one handler type: execution_handler, which is triggered when the action is invoked.
enum:
- execution_handler
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-msgaction-create:
type: object
description: Payload for creating a message action.
required:
- name
- hint
properties:
execution_type:
type: string
enum:
- deluge
- webhook
description: |
Defines how the message action executes its handler.deluge: Handler logic runs on Zoho's platform via Deluge scripts. Default when omitted.webhook: When the action is triggered, Cliq sends a POST request to your execution_url.execution_type is webhook.organization: Visible and accessible to all users within the organization.team: Visible and accessible only to members of specified teams. Requires team_ids field.personal: Visible and accessible only to the creator, but can be shared with other users by adding them as collaborators.scope is set to team. Each ID corresponds to a team within the organization.scope is team.
items:
type: integer
multi_selectable:
type: boolean
description: |
Determines whether the message action can be applied to multiple messages at once. If set to true, users can select multiple messages and invoke the action on all selected messages simultaneously. If false, the action can only be applied to one message at a time.
image:
type: string
description: |
Base64-encoded string representing a custom icon image for the message action. This icon is displayed in the message action menu alongside the action name.
message_types:
type: array
minItems: 1
maxItems: 3
description: |
List of message types that the message action supports. This determines which types of messages the action can be applied to. Allowed values are:text: The action can be applied to text messages.link: The action can be applied to messages containing links.attachment: The action can be applied to messages with attachments.chat: Chat context (chat ID, type, participants).message: Message content and metadata.user: Sender's user profile details.location: Sender's location data.attachments: Attachment metadata and download info.organization: Visible and accessible to all users within the organization.team: Visible and accessible only to members of specified teams. Requires team_ids field.personal: Visible and accessible only to the creator, but can be shared with other users by adding them as collaborators.scope is set to team. Each ID corresponds to a team within the organization.scope is team.
items:
type: integer
multi_selectable:
type: boolean
description: |
Updated multi-selection behavior. If set to true, users can select multiple messages and invoke the action on all selected messages simultaneously. If false, the action can only be applied to one message at a time.
image:
type: string
description: |
Updated Base64-encoded string representing a custom icon image for the message action. This icon is displayed in the message action menu alongside the action name.
message_types:
type: array
minItems: 1
maxItems: 3
description: |
Updated list of message types that the message action supports. Allowed values are:text: The action can be applied to text messages.link: The action can be applied to messages containing links.attachment: The action can be applied to messages with attachments.