openapi: 3.0.0
info:
title: Bots messagecards API
description: "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.
For more information about Bots, please refer to the Bots Help Documentation.
Bot Handlers
\n - 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.
\n - When the trigger event occurs, the corresponding handler executes it's script to perform actions like sending messages, making API calls, or updating data.
\n - By configuring different handlers, you can create bots that respond intelligently to various user interactions and automate complex workflows within Zoho Cliq.
\n
Types of Bot Handlers
\n \n | Handler | \n Description | \n
\n \n | Menu Handler | \n Adds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu. | \n
\n \n | Message Handler | \n Triggered when the bot receives a message. | \n
\n \n | Welcome Handler | \n Defines the greeting message sent when a user subscribes to the bot. | \n
\n \n | Mention Handler | \n Triggered when the bot is @mentioned in a chat or channel. | \n
\n \n | Incoming Webhook Handler | \n Allows external services to post messages into the bot via outgoing webhooks. | \n
\n \n | Context Handler | \n Manages multi-turn conversations, maintaining context across a user's interaction with the bot. | \n
\n
What you can do with the Bots API?
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.
Each bot has an execution_type that defines how its handlers run when a trigger event occurs. The Bots API allows developers to create two types of bots:
Deluge Bots (default)
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.
\n - If
execution_type is not specified during bot creation, it defaults to deluge. \n - Handler logic is defined as a script field (Deluge source code) when creating or updating handlers.
\n - Suitable for teams that want to build and manage bot logic entirely within Zoho's ecosystem.
\n
Webhook Bots
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 execution_url you configure, and your server processes the event and returns a response.
\n - To create a Webhook bot, set
execution_type to webhook during bot creation and provide the execution_url where event payloads should be sent. \n - Your server must be publicly accessible and able to handle incoming POST requests from Zoho Cliq.
\n - 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.
\n
\n"
contact: {}
version: 1.0.0
servers:
- url: https://cliq.zoho.com/api/v3
description: Zoho Cliq US DC
tags:
- name: messagecards
description: APIs for sending structured interactive message cards (Poll, Modern Inline, and Prompt) inside Zoho Cliq conversations.
paths:
/channels/{CHANNEL_UNIQUE_NAME}/message:
post:
summary: Post a message card to a channel
operationId: postMessageCardToChannel
description: "Send a structured Message Card to a specific channel. Use this to deliver polls, inline data cards, or approval prompts into a channel conversation. The card object in the request body varies depending on the card type: poll, modern-inline, or prompt.\n
\n\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
\n Wait time before consecutive API requests.\n
\n"
tags:
- messagecards
parameters:
- name: CHANNEL_UNIQUE_NAME
in: path
required: true
description: The unique name of the channel to post the message card into. To learn how to retrieve this, see CHANNEL_UNIQUE_NAME in the Glossary page.
example: CHANNEL_UNIQUE_NAME
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- card
properties:
text:
type: string
description: 'Fallback plain-text label displayed above the card or in notification previews where cards are not rendered.
Used in: Poll, Modern Inline, and Prompt cards.
'
card:
$ref: '#/components/schemas/CardObject'
slides:
$ref: '#/components/schemas/Slides'
examples:
poll_card:
summary: Poll Card - Sprint priority vote
value:
text: Sprint 42 - Please vote on which feature we prioritize this cycle.
card:
theme: poll
title: Which feature should we prioritize in Sprint 42?
options:
- text: OAuth 2.0 support for third-party integrations
- text: Bulk export for audit logs
- text: Dark mode for the web app
- text: Push notifications for mobile
modern_inline_card:
summary: Modern Inline Card - Support ticket escalation
value:
text: A critical support ticket has been escalated and requires immediate attention.
card:
theme: modern-inline
title: Ticket Escalated - Payment Gateway Timeout
buttons:
- label: Assign to Me
action:
type: invoke.function
data:
name: assign_ticket
- label: View Ticket
action:
type: open.url
data:
web: https://desk.zoho.com/tickets/TKT-00892
slides:
- type: table
title: Ticket Details
data:
headers:
- Field
- Value
rows:
- Field: Ticket ID
Value: '#TKT-00892'
- Field: Priority
Value: Critical
- Field: Reported By
Value: olivia.palmer@zylker.com
- Field: Affected Module
Value: Payment Gateway
- Field: Open Since
Value: 2026-04-16 09:14 AM
prompt_card:
summary: Prompt Card - Deployment approval request
value:
text: Deployment approval required for release v3.6.1 to production.
card:
theme: prompt
title: Approve deployment of v3.6.1 to production? This release includes 4 bug fixes and 1 migration script.
buttons:
- label: Approve
action:
type: invoke.function
data:
name: approve_deployment
- label: Reject
action:
type: invoke.function
data:
name: reject_deployment
- label: View Diff
action:
type: open.url
data:
web: https://git.zylker.com/releases/v3.6.1/diff
responses:
'200':
description: Message card posted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
examples:
poll_card:
summary: Poll Card response
value:
url: /api/v3/channels/engineering/message
type: message
data:
id: '1701234567890_1234567890'
card:
theme: poll
title: Which feature should we prioritize in Sprint 42?
options:
- text: OAuth 2.0 support for third-party integrations
votes: 0
- text: Bulk export for audit logs
votes: 0
- text: Dark mode for the web app
votes: 0
- text: Push notifications for mobile
votes: 0
modern_inline_card:
summary: Modern Inline Card response
value:
url: /api/v3/channels/support/message
type: message
data:
id: '1701234567891_1234567891'
card:
theme: modern-inline
title: Ticket Escalated - Payment Gateway Timeout
slides:
- type: table
title: Ticket Details
data:
headers:
- Field
- Value
rows:
- Field: Ticket ID
Value: '#TKT-00892'
- Field: Priority
Value: Critical
prompt_card:
summary: Prompt Card response
value:
url: /api/v3/channels/devops/message
type: message
data:
id: '1701234567892_1234567892'
card:
theme: prompt
title: Approve deployment of v3.6.1 to production?
'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.
'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.Channels.CREATE
/chats/{CHAT_ID}/messages:
post:
summary: Post a message card to a chat
operationId: postMessageCardToChat
description: "Send a structured Message Card into any chat conversation. Use this to deliver polls, inline data cards, or approval prompts into a direct message, group chat, or channel conversation. The card object in the request body varies depending on the card type: poll, modern-inline, or prompt.\n
\nRecommended for bot and agentic workflows where the target conversation is resolved dynamically at runtime.\n
\n\n Threshold limit: 20 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
\n Wait time before consecutive API requests.\n
\n"
tags:
- messagecards
parameters:
- name: CHAT_ID
in: path
required: true
description: Unique identifier of the chat where the message card should be posted. To learn how to retrieve this ID, see CHAT_ID in the Glossary page.
example: CHAT_ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- card
properties:
text:
type: string
description: 'Fallback plain-text label displayed above the card or in notification previews where cards are not rendered.
Used in: Poll, Modern Inline, and Prompt cards.
'
card:
$ref: '#/components/schemas/CardObject'
slides:
$ref: '#/components/schemas/Slides'
examples:
poll_card:
summary: Poll Card - Sprint priority vote
value:
text: Sprint 42 - Please vote on which feature we prioritize this cycle.
card:
theme: poll
title: Which feature should we prioritize in Sprint 42?
options:
- text: OAuth 2.0 support for third-party integrations
- text: Bulk export for audit logs
- text: Dark mode for the web app
- text: Push notifications for mobile
modern_inline_card:
summary: Modern Inline Card - Support ticket escalation
value:
text: A critical support ticket has been escalated and requires immediate attention.
card:
theme: modern-inline
title: Ticket Escalated - Payment Gateway Timeout
buttons:
- label: Assign to Me
action:
type: invoke.function
data:
name: assign_ticket
- label: View Ticket
action:
type: open.url
data:
web: https://desk.zoho.com/tickets/TKT-00892
slides:
- type: table
title: Ticket Details
data:
headers:
- Field
- Value
rows:
- Field: Ticket ID
Value: '#TKT-00892'
- Field: Priority
Value: Critical
- Field: Reported By
Value: olivia.palmer@zylker.com
- Field: Affected Module
Value: Payment Gateway
- Field: Open Since
Value: 2026-04-16 09:14 AM
prompt_card:
summary: Prompt Card - Deployment approval request
value:
text: Deployment approval required for release v3.6.1 to production.
card:
theme: prompt
title: Approve deployment of v3.6.1 to production? This release includes 4 bug fixes and 1 migration script.
buttons:
- label: Approve
action:
type: invoke.function
data:
name: approve_deployment
- label: Reject
action:
type: invoke.function
data:
name: reject_deployment
- label: View Diff
action:
type: open.url
data:
web: https://git.zylker.com/releases/v3.6.1/diff
responses:
'200':
description: Message card posted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
examples:
poll_card:
summary: Poll Card response
value:
url: /api/v3/chats/CHAT_ID/messages
type: message
data:
id: '1701234567890_1234567890'
card:
theme: poll
title: Which feature should we prioritize in Sprint 42?
options:
- text: OAuth 2.0 support for third-party integrations
votes: 0
- text: Bulk export for audit logs
votes: 0
- text: Dark mode for the web app
votes: 0
- text: Push notifications for mobile
votes: 0
modern_inline_card:
summary: Modern Inline Card response
value:
url: /api/v3/chats/CHAT_ID/messages
type: message
data:
id: '1701234567891_1234567891'
card:
theme: modern-inline
title: Ticket Escalated - Payment Gateway Timeout
slides:
- type: table
title: Ticket Details
data:
headers:
- Field
- Value
rows:
- Field: Ticket ID
Value: '#TKT-00892'
- Field: Priority
Value: Critical
prompt_card:
summary: Prompt Card response
value:
url: /api/v3/chats/CHAT_ID/messages
type: message
data:
id: '1701234567892_1234567892'
card:
theme: prompt
title: Approve deployment of v3.6.1 to production?
'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.
'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.Messages.CREATE
components:
schemas:
CardObject:
type: object
description: "Defines the interactive card to be rendered inside the message. The theme field\nselects the card type and determines which fields are required. For a quick reference of\nrequired and optional fields per theme, see the Available Themes table in the overview above.\n
\nPoll card fields\n\n - theme
string: Must be poll. \n - title
string: The poll question displayed at the top of the card. Maximum 200 characters. \n - options
array: List of voting choices. Minimum 2, maximum 10 items.\n \n - options[].text
string: Display label for the poll option. Maximum 100 characters. \n
\n \n
\nModern Inline card fields\n\n - theme
string: Must be modern-inline. \n - title
string: Card header text displayed at the top of the card. Maximum 200 characters. \n - thumbnail
string: Optional. Publicly accessible HTTPS URL of a thumbnail image shown in the card header. \n - sections
array: Optional. One or more labeled field sections displayed in the card body. Each section groups related key-value pairs under an optional heading.\n \n - sections[].title
string: Optional section heading displayed above the fields. \n - sections[].fields
array: List of key-value field pairs.\n \n - fields[].title
string: Field label (key). \n - fields[].value
string: Field value. \n
\n \n
\n \n - buttons
array: Optional. Action buttons rendered at the bottom of the card. Maximum 5. See Button fields below. \n
\nPrompt card fields\n\n - theme
string: Must be prompt. \n - title
string: The prompt question or alert text presented to the user. Maximum 200 characters. \n - buttons
array: Action buttons for the user to respond with. Minimum 1, maximum 5. See Button fields below. \n
\nButton fields (applicable to modern-inline and prompt themes)\n\n - buttons[].label
string: Text displayed on the button. Maximum 30 characters. \n - buttons[].action.type
string: Determines how Cliq handles the button click.\n \n open.url: Opens a URL in the user's default browser. Requires action.data.web (string).invoke.function: Triggers a Cliq Function by name. Requires action.data.name (string).system.api: Calls a Cliq internal system API. Requires action.data.api (string).invoke.bot: Sends a message to a bot. Requires action.data.bot_name and action.data.message.preview.url: Opens a URL inside a Cliq preview panel without leaving the conversation. Requires action.data.web (string).
\n \n - buttons[].action.data
object: The payload passed to the action handler. Expected fields depend on action.type as listed above. \n
\nNote: To render supporting structured content such as tables, lists, or labelled records alongside a card,\nuse the top-level slides array in the message payload. slides is independent of the card object\nand can be combined with any card theme. For details on supported slide formats, see\nMessage Content.\n"
required:
- theme
- title
properties:
theme:
type: string
enum:
- poll
- modern-inline
- prompt
description: "Card theme identifier. Determines the card type to render.
\nAllowed values:
\n\n poll: Renders a poll card with voting options, live vote counts, and percentages.modern-inline: Renders a rich inline card with a header, optional field sections, and action buttons.prompt: Renders a focused prompt card with a question and quick-reply action buttons.
\n"
example: poll
title:
type: string
maxLength: 200
description: 'The card header or question text displayed at the top of the card.
Maximum length: 200 characters.
'
example: Where should we have the team lunch?
options:
type: array
minItems: 2
maxItems: 10
description: 'Applicable for poll theme only.
List of voting options. Each option is rendered as a selectable row with a live vote count and percentage bar.
Minimum: 2 options. Maximum: 10 options.
'
items:
type: object
required:
- text
properties:
text:
type: string
maxLength: 100
description: Display label for the poll option. Maximum 100 characters.
example: Italian
thumbnail:
type: string
description: 'Applicable for modern-inline theme only.
URL of an image to display as a thumbnail in the card header. Must be a publicly accessible HTTPS URL.
'
example: https://www.zoho.com/cliq/help/restapi/images/poll_icon.png
sections:
type: array
description: 'Applicable for modern-inline theme only.
List of field sections. Each section groups related labeled key-value fields under an optional section title.
'
items:
type: object
properties:
title:
type: string
description: Optional section heading displayed above the fields.
example: Summary
fields:
type: array
description: List of key-value field pairs displayed in this section.
items:
type: object
required:
- title
- value
properties:
title:
type: string
description: Field label (key).
example: Account
value:
type: string
description: Field value.
example: Zylker Corp
buttons:
type: array
maxItems: 5
description: 'Applicable for modern-inline and prompt themes.
List of action buttons rendered inside the card. Each button executes an action when clicked by the user.
Maximum: 5 buttons. Minimum 1 required for prompt.
'
items:
$ref: '#/components/schemas/CardButton'
MessageResponse:
type: object
description: Response returned after a message card is successfully posted.
properties:
url:
type: string
description: Endpoint URL associated with the response.
example: /api/v3/channels/announcements/message
type:
type: string
description: Resource type of the response.
example: message
data:
type: object
description: Payload containing the posted message details.
properties:
id:
type: string
description: Unique identifier of the posted message.
example: '1701234567890_1234567890'
card:
type: object
description: The card object as stored by Cliq after posting.
additionalProperties: true
additionalProperties: true
Slides:
type: array
description: "An array of structured content blocks rendered below the card inside the message.\nslides is a top-level field in the message payload - it sits alongside\ntext and card, and is not nested inside card.\n
\nMultiple slide blocks can be included in a single message, and they are rendered in the\norder they appear in the array. slides is most commonly paired with the\nmodern-inline card theme to display supporting data such as tables, lists,\nor labelled records alongside the card header, but it is compatible with all card themes.\n
\nEach slide block requires a type field that determines how the content is rendered,\nan optional title heading, and a data payload whose structure\ndepends on the slide type.\n
\nSupported slide types\n\n \n | Type | \n Renders | \n data structure | \n
\n \n table | \n A data table with column headers and rows. | \n Object with headers (array of strings) and rows (array of objects where each key maps to a header). | \n
\n \n list | \n A bulleted list of items. | \n Array of strings, each representing one list item. | \n
\n \n label | \n Key-value pairs in a definition-list style. | \n Array of objects, each with label (string) and value (string). | \n
\n \n images | \n One or more inline images. | \n Array of publicly accessible HTTPS image URL strings. | \n
\n \n text | \n A plain or formatted text block. | \n A string containing the text content to display. | \n
\n
\n
\nFor full details on each slide type, including field-level descriptions and payload examples,\nrefer to Message Content.\n"
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- table
- list
- label
- images
- text
description: "The slide content type. Determines how the data payload is rendered.
\nAllowed values:
\n\n table: Renders a data table with column headers and rows.list: Renders a bulleted list of items.label: Renders key-value pairs in a definition-list style.images: Renders one or more inline images from HTTPS URLs.text: Renders a plain or formatted text block.
\n"
example: table
title:
type: string
description: Optional heading displayed above the slide content.
example: Ticket Details
data:
description: "Content payload for the slide. Structure depends on type:
\n\n - table: Object with
headers (array of strings) and rows (array of objects). \n - list: Array of strings.
\n - label: Array of objects, each with
label and value. \n - images: Array of image URL strings.
\n - text: A string containing the text content to display.
\n
\n"
example:
headers:
- Field
- Value
rows:
- Field: Ticket ID
Value: '#TKT-00892'
- Field: Priority
Value: Critical
CardButton:
type: object
description: An action button rendered inside a Message Card. When clicked by a user, the button executes the specified action.
required:
- label
- action
properties:
label:
type: string
maxLength: 30
description: 'Display text shown on the button.
Maximum length: 30 characters.
'
example: Approve
action:
type: object
description: 'Defines the action executed when the button is clicked. The type field determines the action category and the expected structure of the data payload.
'
required:
- type
- data
properties:
type:
type: string
enum:
- open.url
- invoke.function
- system.api
- invoke.bot
- preview.url
description: "The action type. Determines how Cliq handles the button click.
\nAllowed values:
\n\n open.url: Opens a URL in the user's default browser. Requires action.data.web (string).invoke.function: Triggers a Cliq Function by name. Requires action.data.name (string).system.api: Calls a Cliq internal system API. Requires action.data.api (string).invoke.bot: Sends a message to a bot. Requires action.data.bot_name and action.data.message.preview.url: Opens a URL inside a Cliq preview panel without leaving the conversation. Requires action.data.web (string).
\n"
example: invoke.function
data:
type: object
additionalProperties: true
description: "Payload passed to the action handler. The expected fields depend on type:
\n\n - open.url: Requires
web (string - the URL to open). \n - invoke.function: Requires
name (string - Cliq Function name). \n - system.api: Requires
api (string - the internal API path). \n - invoke.bot: Requires
bot_name and message. \n - preview.url: Requires
web (string - the URL to preview). \n
\n"
example:
name: ack_alert
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoCliq.Bots.READ: Read Bot Information
ZohoCliq.Bots.CREATE: Create Bots
ZohoCliq.Bots.UPDATE: Update Bots
ZohoCliq.Bots.DELETE: Delete Bots
ZohoCliq.Webhooks.CREATE: Post messages to conversations via webhooks
ZohoCliq.BotMessages.CREATE: Send messages via bot incoming webhooks
ZohoCliq.Channels.UPDATE: Update Channel Settings
externalDocs:
description: Find out more about Zoho Cliq APIs V3
url: https://www.zoho.com/cliq/help/restapi/v3/