openapi: 3.0.0
info:
title: Bots mentions API
description: "<p>Bots are conversational assistants designed to automate repetitive tasks and manage simple user interactions. Their behavior is fully customizable through predefined Bot Handlers, which are activated by specific actions or through Webhooks that communicate with your own external server.</p> <p>For more information about Bots, please refer to the <b><a href=\"https://www.zoho.com/cliq/help/platform/bots.html\" target=\"_blank\">Bots Help Documentation</a></b>.</p> <p><b>Bot Handlers</b></p> <ul>\n <li>Bot Handlers are the building blocks of a bot's functionality. Each handler is associated with a specific trigger event, such as receiving a direct message, being @mentioned in a channel, or a user subscribing to the bot.</li>\n <li>When the trigger event occurs, the corresponding handler executes it's script to perform actions like sending messages, making API calls, or updating data.</li>\n <li>By configuring different handlers, you can create bots that respond intelligently to various user interactions and automate complex workflows within Zoho Cliq.</li>\n</ul> <p><b>Types of Bot Handlers</b></p> <table style=\"border-collapse: collapse; width: 100%;\">\n <tr>\n <th style=\"padding: 8px; text-align: left; border: 1px solid #ddd;\">Handler</th>\n <th style=\"padding: 8px; text-align: left; border: 1px solid #ddd;\">Description</th>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Menu Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Adds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu.</td>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Message Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Triggered when the bot receives a message.</td>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Welcome Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Defines the greeting message sent when a user subscribes to the bot.</td>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Mention Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Triggered when the bot is @mentioned in a chat or channel.</td>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Incoming Webhook Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Allows external services to post messages into the bot via outgoing webhooks.</td>\n </tr>\n <tr>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Context Handler</td>\n <td style=\"padding: 8px; border: 1px solid #ddd;\">Manages multi-turn conversations, maintaining context across a user's interaction with the bot.</td>\n </tr>\n</table> <p><b>What you can do with the Bots API?</b></p> <p>With the Bots API, you can retrieve information about a specific bot, list all bots within your organization, manage configurations specific to handlers, trigger bot calls programmatically, manage subscribers, and much more.</p> <p>Each bot has an <code>execution_type</code> that defines how its handlers run when a trigger event occurs. The Bots API allows developers to create two types of bots:</p> <p id=\"deluge-bots\"><b>Deluge Bots (default)</b><br> Deluge bot executes handler logic using Zoho's Deluge scripting language, hosted entirely within the Zoho Cliq Developer platform, where no external server is required.</p> <ul>\n <li>If <code>execution_type</code> is not specified during bot creation, it defaults to deluge.</li>\n <li>Handler logic is defined as a script field (Deluge source code) when creating or updating handlers.</li>\n <li>Suitable for teams that want to build and manage bot logic entirely within Zoho's ecosystem.</li>\n</ul> <p id=\"webhook-bots\"><b>Webhook Bots</b><br> A Webhook bot delegates all handler execution to your own external server. When a trigger event fires, Zoho Cliq sends an HTTP POST request to the <code>execution_url</code> you configure, and your server processes the event and returns a response.</p> <ul>\n <li>To create a Webhook bot, set <code>execution_type</code> to webhook during bot creation and provide the <code>execution_url</code> where event payloads should be sent.</li>\n <li>Your server must be publicly accessible and able to handle incoming POST requests from Zoho Cliq.</li>\n <li>Ideal for teams seeking complete control over bot logic and possessing the resources to manage an external server. Also suitable for integrations requiring access to external databases, third-party APIs, or custom business logic that cannot be executed in Deluge.</li>\n</ul>\n"
contact: {}
version: 1.0.0
servers:
- url: https://cliq.zoho.com/api/v3
description: Zoho Cliq US DC
tags:
- name: mentions
description: Mentions Module
paths:
/mentions:
get:
summary: Retrieve Mentions and Replies
operationId: getMentions
description: "Fetches a list of messages in which the authenticated user has been mentioned or replied to.<br><br>\nThe results are returned in descending order (newest to oldest) and can be filtered using various query parameters such as time range, chat IDs, sender user IDs, and activity type (mentions or replies).<br><br>\nThis endpoint allows users to easily track conversations that require their attention based on mentions and replies.\n<br><br>\n<p>\n <b>Threshold limit</b>: 30 requests per min per user<br>\n Number of API calls allowed within a minute.<br><br>\n <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>\n</p>\n"
parameters:
- name: from_time
in: query
required: false
schema:
type: integer
format: int64
description: "<ul>\n <li>Return mentions created after this epoch time (ms).</li>\n <li>By default, mentions from the last 30 days are returned.</li>\n <li>If both <code>from_time</code> and <code>to_time</code> are provided, the API will return mentions created within that time range.</li>\n</ul>\n<b>Example:</b> 1622217600000 (June 1, 2021 12:00:00 AM GMT).\n"
- name: to_time
in: query
required: false
schema:
type: integer
format: int64
description: "<ul> \n <li>Return mentions created before this epoch time (ms).</li>\n <li>By default, mentions up to the current time are returned.</li>\n <li>If both <code>from_time</code> and <code>to_time</code> are provided, the API will return mentions created within that time range.</li>\n</ul>\n<b>Example:</b> 1624809600000 (July 1, 2021 12:00:00 AM GMT). \n"
- name: limit
in: query
required: false
schema:
type: integer
default: 25
maximum: 100
description: "Maximum number of mentions to return in the response.<br>\n<ul>\n <li>Default value is 25 if not specified.</li>\n <li>Maximum allowed value is 100.</li>\n <li>If the total number of mentions exceeds this limit, a pagination token will be provided in the response to fetch the next set of results.</li>\n</ul>\n"
- name: next_token
in: query
required: false
schema:
type: string
description: 'Pagination token to retrieve the next set of mentions when the total number exceeds the specified limit. This token is provided in the response when there are more mentions to fetch.
'
- name: chid
in: query
required: false
schema:
type: string
description: 'Filter mentions by a specific chat ID.<br>
To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
'
- name: chat_ids
in: query
required: false
schema:
type: string
description: 'Filter mentions by multiple chat IDs (comma-separated, maximum 5).<br>
Example: <code>chat_ids = CT_1207124854_60002085329,CT_17960055085329-T-12915799199</code><br>
To learn how to retrieve these IDs, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
'
- name: user_ids
in: query
required: false
schema:
type: string
description: 'Filter mentions by sender user IDs (comma-separated, maximum 5).<br>
Example: <code>user_ids = 60040396507,60040376665</code><br>
To learn how to retrieve these IDs, see <a href="/cliq/help/restapi/v3/glossary/#USER_ID">USER_ID</a> in the Glossary page.
'
- name: type
in: query
required: false
schema:
type: string
enum:
- mentions
- replies
- all
default: mentions
description: "Filter results by activity type.<br>\n<ul>\n <li><code>mentions</code>: Returns messages where the user was mentioned.</li>\n <li><code>replies</code>: Returns messages where the user was replied to.</li>\n <li><code>all</code>: Returns both mentions and replies.</li>\n</ul>\n<b>Default</b>: mentions \n"
responses:
'200':
description: Mentions retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/get-mentions-response'
'400':
description: Invalid query parameter value.
content:
application/json:
schema:
$ref: '#/components/schemas/mentions-error-response'
example:
code: INVALID_PARAMS
message: Invalid query parameter value.
'401':
description: Missing or invalid authentication token.
content:
application/json:
schema:
$ref: '#/components/schemas/mentions-error-response'
example:
code: UNAUTHORIZED
message: Missing or invalid authentication token.
'500':
description: Internal server error while fetching mentions.
content:
application/json:
schema:
$ref: '#/components/schemas/mentions-error-response'
example:
code: MENTIONS_FETCH_FAILED
message: Internal server error while fetching mentions.
security:
- Cliq_Auth:
- ZohoCliq.Chats.READ
tags:
- mentions
/chats/{CHAT_ID}/messages:
post:
summary: Mentioning a User
operationId: mentioningUser
description: 'To mention a user, use the syntax <b>{@zohoid}</b> or <b>{@email}</b>.<br><br>
When you mention a user in any team-level or organization-level channel, the user will be notified. This syntax applies only to the <code>text</code> and <code>comments</code> fields of the payload.
To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
'
parameters:
- name: CHAT_ID
in: path
required: true
schema:
type: string
example: CHAT_ID
description: Unique identifier of the chat where the message needs to be sent.
requestBody:
required: true
content:
application/json:
examples:
userid:
summary: User mention with userID
value:
text: Hey there {@userid}, please review the latest project updates
email:
summary: User mention with user email
value:
text: Hey there {@scott.fisher@zylker.com}, please review the latest project updates
schema:
type: object
required:
- text
properties:
text:
type: string
description: 'The text content of the message to be sent.<br>
<b>Maximum length</b>: 10,000 characters.
'
maxLength: 10000
example: Hi Team! Please find the sales performance chart for this quarter.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/empty-response'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Webhooks.CREATE
tags:
- mentions
/chats/{CHAT_ID1}/messages:
post:
summary: Silent mentions
x-display-path: /chats/{CHAT_ID}/messages
x-virtual-endpoint: true
x-note: 'CHAT_ID1 is a documentation alias for CHAT_ID path parameter used in silentMentions operation. This alias is used to document the silent mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the message text syntax differs. The actual endpoint for silentMentions operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: silentMentions
description: 'Silent mentions allow you to reference a user in a conversation without triggering a notification.<br><br>
Use the syntax <code>[User Name](zohoid:userid)</code> or <code>[User Name](mail:user_email)</code> to mention a user silently in any conversation. This will not notify the user. This format can also be used to mention a user in fields other than the <code>text</code> and <code>comments</code> keys.
'
parameters:
- name: CHAT_ID1
in: path
required: true
schema:
type: string
example: CHAT_ID
description: 'Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
<b>Note:</b> <code>CHAT_ID1</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Silent mentions" use case separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the message text syntax differs.
'
requestBody:
required: true
content:
application/json:
examples:
userid:
summary: Silent mention with userID
value:
text: Hey there [Scott Fisher](zohoid:873421), could you check the campaign details when you get a chance?
email:
summary: Silent mention with user email
value:
text: Hey there [Scott Fisher](mail:scott.fisher@zylker.com), could you check the campaign details when you get a chance?
schema:
type: object
required:
- text
properties:
text:
type: string
description: 'The text content of the message to be sent.<br>
<b>Maximum length</b>: 10,000 characters.
'
maxLength: 10000
example: Hi Team! Please find the sales performance chart for this quarter.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/empty-response'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Webhooks.CREATE
tags:
- mentions
/chats/{CHAT_ID2}/messages:
post:
summary: Mentioning a Channel
x-display-path: /chats/{CHAT_ID}/messages
x-virtual-endpoint: true
x-note: 'CHAT_ID2 is a documentation alias for CHAT_ID path parameter used in mentioningChannel operation. This alias is used to document the channel mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningChannel operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: mentioningChannel
description: 'To mention a channel, use the syntax <code>{#CHANNEL_ID}</code>.<br><br>
When you mention a team-level or organization-level channel, all participants of that channel will be notified. Additionally, an informational message will be posted in the channel indicating that it has been mentioned.
'
parameters:
- name: CHAT_ID2
in: path
required: true
schema:
type: string
example: CHAT_ID
description: 'Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
<b>Note:</b> <code>CHAT_ID2</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning a Channel" use case separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the message content pattern differs.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: "The text content of the message to be sent.<br>\n <b>Maximum length</b>: 10,000 characters.\n"
maxLength: 10000
example: Please review the latest deployment updates in {#CHANNEL_ID} and share your feedback.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/empty-response'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Webhooks.CREATE
tags:
- mentions
/chats/{CHAT_ID3}/messages:
post:
summary: Mentioning all users in a channel
x-display-path: /chats/{CHAT_ID}/messages
x-virtual-endpoint: true
x-note: 'CHAT_ID3 is a documentation alias for CHAT_ID path parameter used in mentioningAllUsers operation. This alias is used to document the mention-all use case separately while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningAllUsers operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: mentioningAllUsers
description: 'To mention all users in a channel, use the syntax {@all}.<br>
This will notify every participant who is a member of the channel.<br>
<b>Note:</b> The ability to use {@all} depends on the authenticated user''s role and channel permissions. If the user does not have permission to mention all participants, the message posting request will fail.
'
parameters:
- name: CHAT_ID3
in: path
required: true
schema:
type: string
example: CHAT_ID
description: 'Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v3/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
<b>Note:</b> <code>CHAT_ID3</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning all users in a channel" use case separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the message content pattern differs.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: "The text content of the message to be sent.<br>\n <b>Maximum length</b>: 10,000 characters.\n"
maxLength: 10000
example: Attention @all, please review the quarterly sales report and share your inputs before tomorrow’s strategy meeting.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/empty-response'
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
'404':
description: Invalid URL.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
'405':
description: Method Not Allowed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
'406':
description: Not Acceptable.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The response has been received but the requested response type is not supported by the browser.
'429':
description: Too many requests.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Cliq server encountered an error which prevents it from fulfilling the request.
security:
- Cliq_Auth:
- ZohoCliq.Webhooks.CREATE
tags:
- mentions
/chats/{CHAT_ID5}/messages:
post:
summary: Mentioning a Team
x-display-path: /chats/{CHAT_ID}/messages
x-virtual-endpoint: true
x-note: 'CHAT_ID5 is a documentation alias for CHAT_ID path parameter used in mentioningTeam operation. This alias is used to document the team mention use case separately while keeping it under the same POST /chats/{CHAT_
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-cliq/refs/heads/main/openapi/zoho-cliq-mentions-api-openapi.yml