openapi: 3.0.0 info: title: Message Cards description: | Message Cards are structured, interactive message formats in Zoho Cliq that go beyond plain text to deliver rich, engaging content inside conversations. They are used to present polls, inline data displays, and interactive prompts directly within a chat or channel, enabling bots and integrations to collect input, display structured information, and drive actions from users without leaving the conversation.

Message Cards are sent as part of the standard Post Message payload by setting the card object inside the message body. The theme field inside card determines which card type is rendered.

Not sure how to structure your card? Use the Message Builder to visually design and preview your card payload before integrating.

Try Message Builder

Available Themes

Theme Description Required fields Optional fields
poll Renders a poll card that lets users vote on one or more options. Tracks and displays live vote counts and percentages. theme, title, options -
modern-inline Renders a rich inline card with a header, sections of labeled fields, and optional action buttons. Pair with slides for supporting data. theme, title thumbnail, sections, buttons
prompt Renders a focused prompt card with a question and a set of quick-reply or action buttons for the user to respond to. theme, title, buttons -

How Message Cards work contact: {} version: 1.0.0 externalDocs: description: Find out more about Zoho Cliq APIs V3 url: https://www.zoho.com/cliq/help/restapi/v3/ servers: - url: https://cliq.zoho.com/api/v3 description: Zoho Cliq US Data Centre 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.

Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.

Lock period: 10 minutes
Wait time before consecutive API requests.

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.

Recommended for bot and agentic workflows where the target conversation is resolved dynamically at runtime.

Threshold limit: 20 requests per min per user
Number of API calls allowed within a minute.

Lock period: 10 minutes
Wait time before consecutive API requests.

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 selects the card type and determines which fields are required. For a quick reference of required and optional fields per theme, see the Available Themes table in the overview above.

Poll card fields Modern Inline card fields Prompt card fields Button fields (applicable to modern-inline and prompt themes) Note: To render supporting structured content such as tables, lists, or labelled records alongside a card, use the top-level slides array in the message payload. slides is independent of the card object and can be combined with any card theme. For details on supported slide formats, see Message Content. required: - theme - title properties: theme: type: string enum: - poll - modern-inline - prompt description: | Card theme identifier. Determines the card type to render.
Allowed values:
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' 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.
Allowed values:
example: invoke.function data: type: object additionalProperties: true description: | Payload passed to the action handler. The expected fields depend on type:
example: name: ack_alert 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. slides is a top-level field in the message payload - it sits alongside text and card, and is not nested inside card.

Multiple slide blocks can be included in a single message, and they are rendered in the order they appear in the array. slides is most commonly paired with the modern-inline card theme to display supporting data such as tables, lists, or labelled records alongside the card header, but it is compatible with all card themes.

Each slide block requires a type field that determines how the content is rendered, an optional title heading, and a data payload whose structure depends on the slide type.

Supported slide types
Type Renders data structure
table A data table with column headers and rows. Object with headers (array of strings) and rows (array of objects where each key maps to a header).
list A bulleted list of items. Array of strings, each representing one list item.
label Key-value pairs in a definition-list style. Array of objects, each with label (string) and value (string).
images One or more inline images. Array of publicly accessible HTTPS image URL strings.
text A plain or formatted text block. A string containing the text content to display.

For full details on each slide type, including field-level descriptions and payload examples, refer to Message Content. 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.
Allowed values:
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:
example: headers: - Field - Value rows: - Field: Ticket ID Value: '#TKT-00892' - Field: Priority Value: Critical NoResponse: type: object description: Represents an empty successful response where no payload is returned. properties: Response Code: type: string description: HTTP response code indicating no content is returned. example: 204 No response GenericResponse: type: object description: Generic successful response envelope. properties: url: type: string description: Endpoint URL associated with the response. type: type: string description: Resource type returned by the API. data: type: object description: Resource payload. additionalProperties: true additionalProperties: true securitySchemes: Cliq_Auth: type: oauth2 x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f flows: implicit: authorizationUrl: https://accounts.zoho.com/oauth/v2/auth scopes: ZohoCliq.Messages.CREATE: Send messages to users and chats ZohoCliq.Channels.CREATE: Post messages to channels ZohoCliq.Webhooks.CREATE: Post messages via webhooks