openapi: 3.0.0
info:
title: Bots messageformat 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: messageformat
description: Message Format Module
paths:
/chats/{CHAT_ID}/messages:
post:
summary: Plain text
operationId: textmessageformat
description: 'Use this API to send plain text messages in Cliq.
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:
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: Hello team, please review the latest project updates.
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:
- messageformat
/chats/{CHAT_ID1}/messages:
post:
summary: Table
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 table operation. This alias is used to document the table message format as a separate operation while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the structured message payload differs. The actual endpoint for table operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: table
description: 'Use this API to send message content formatted as a table.
<br><br>
<b>Note:</b> All structured content must be included within the <code>slides</code> JSON object.
'
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 "Table" message format separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the structured message payload differs.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-table-message-request-body'
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:
- messageformat
/chats/{CHAT_ID2}/messages:
post:
summary: List
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 list operation. This alias is used to document the list message format as a separate operation while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the structured message payload differs. The actual endpoint for list operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: list
description: 'Use this API to send message content formatted as a list.
<br><br>
<b>Note:</b> All structured content must be included within the <code>slides</code> JSON object.
'
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 "List" message format separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the structured message payload differs.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-list-message-request-body'
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:
- messageformat
/chats/{CHAT_ID3}/messages:
post:
summary: Label
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 label operation. This alias is used to document the label message format as a separate operation while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the structured message payload differs. The actual endpoint for label operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: label
description: 'Use this API to send message content formatted as a label.
<br><br>
<b>Note:</b> All structured content must be included within the <code>slides</code> JSON object.
'
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 "Label" message format separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the structured message payload differs.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-label-message-request-body'
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:
- messageformat
/chats/{CHAT_ID4}/messages:
post:
summary: Image
x-display-path: /chats/{CHAT_ID}/messages
x-virtual-endpoint: true
x-note: 'CHAT_ID4 is a documentation alias for CHAT_ID path parameter used in image operation. This alias is used to document the image message format as a separate operation while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the structured message payload differs. The actual endpoint for image operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: image
description: 'Use this API to send message content formatted as an image.
<br><br>
<b>Note:</b> All structured content must be included within the <code>slides</code> JSON object.
'
parameters:
- name: CHAT_ID4
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_ID4</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Image" message format separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the structured message payload differs.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-image-message-request-body'
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:
- messageformat
/chats/{CHAT_ID5}/messages:
post:
summary: Charts
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 charts operation. This alias is used to document the charts message format as a separate operation while keeping it under the same POST /chats/{CHAT_ID}/messages endpoint, because the actual API path does not change and only the structured message payload differs. The actual endpoint for charts operation remains /chats/{CHAT_ID}/messages as specified in the paths object.
'
operationId: charts
description: 'Use this API to send message content formatted as a chart.
<br><br>
<b>Note:</b> All structured content must be included within the <code>slides</code> JSON object.
'
parameters:
- name: CHAT_ID5
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_ID5</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Charts" message format separately while sharing the same <code>/chats/{CHAT_ID}/messages</code> endpoint, since the path is unchanged and only the structured message payload differs.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-chart-message-request-body'
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:
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-cliq/refs/heads/main/openapi/zoho-cliq-messageformat-api-openapi.yml