openapi: 3.0.0
info:
title: Bots messages 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: messages
description: Messages Module
paths:
/chats/{CHAT_ID}/messagess:
delete:
summary: Delete multiple messages
operationId: deleteMultipleMessagesV3
description: "Deletes up to 25 messages in a chat in a single request. Returns a per-message result indicating success or failure for each ID.
\nAdmins deleting messages on behalf of other users must supply a reason(an optional comment) can also be provided.\n
\n\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests.
\n
\n\n \n !\n Possible Error Codes\n Click to expand\n
\n \n
\n
\n \n \n | Error Code | \n Description | \n
\n \n \n \n | message_delete_limit_exceeded | \n You can only delete up to 25 messages at once. | \n
\n \n | invalid_parameters | \n The message_ids parameter is invalid or empty. | \n
\n \n | invalid_delete_reason | \n The provided reason for deletion is not valid. | \n
\n \n | access_denied | \n You do not have permission to delete one or more of the selected messages. | \n
\n \n | message_delete_timeout | \n The time limit to delete one or more of these messages has expired. | \n
\n \n | message_not_found | \n Requested message could not be found. | \n
\n \n | chat_not_found | \n The requested chat does not exist or you are not a participant. | \n
\n \n
\n
\n
\n
Error Response Format\n
When an error occurs, the API returns a JSON response in this format:
\n
{\"message\": \"A human-readable description of the error.\", \"code\": \"error_code\"}\n
where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.
\n
\n
\n"
parameters:
- name: CHAT_ID
in: path
required: true
schema:
type: string
example: CHAT_ID
description: The unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page.
- name: message_ids
in: query
required: true
schema:
type: string
description: 'Comma-separated list of message IDs to delete.
Maximum of 25 IDs allowed.
'
- name: reason
in: query
required: false
schema:
type: string
enum:
- irrelevant_information
- obscene_content
- others
description: "Reason for deletion when an admin is deleting messages on behalf of other users.
\nAllowed values:
\n\n irrelevant_information: The message contains information that is no longer relevant.obscene_content: The message contains inappropriate or offensive content.others: Any other reason not covered by the above options.
\n"
- name: comment
in: query
required: false
schema:
type: string
maxLength: 250
description: 'Optional comment providing additional context for the deletion reason when an admin is deleting messages on behalf of other users.
Maximum length: 250 characters.
'
responses:
'200':
description: The request was successfully completed. Returns a per-message result.
content:
application/json:
examples:
all_success:
summary: All messages deleted successfully
value:
type: message.delete_result
data:
- id: '1773813859592_51531973059'
status: success
- id: '1773813860210_51531973060'
status: success
- id: '1773813861300_51531973061'
status: success
partial_failure:
summary: Partial success - one message failed
value:
type: message.delete_result
data:
- id: '1773813859592_51531973059'
status: success
- id: '1773813860210_51531973060'
status: success
- id: '1773813861300_51531973061'
status: failed
error:
code: access_denied
message: You do not have permission to delete this message.
schema:
type: object
properties:
type:
type: string
example: message.delete_result
data:
type: array
items:
type: object
properties:
id:
type: string
status:
type: string
enum:
- success
- failed
error:
type: object
properties:
code:
type: string
message:
type: string
'400':
description: Bad Request.
content:
application/json:
examples:
limit_exceeded:
summary: Too many message IDs
value:
code: message_delete_limit_exceeded
message: You can only delete up to 25 messages at once.
invalid_params:
summary: Invalid or empty message_ids
value:
code: invalid_parameters
message: The message_ids parameter is invalid or empty.
invalid_reason:
summary: Invalid delete reason
value:
code: invalid_delete_reason
message: The provided reason for deletion is not valid.
schema:
type: object
properties:
code:
type: string
message:
type: string
'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:
examples:
access_denied:
summary: Permission denied
value:
code: access_denied
message: You do not have permission to delete one or more of the selected messages.
delete_timeout:
summary: Delete time limit expired
value:
code: message_delete_timeout
message: The time limit to delete one or more of these messages has expired.
schema:
type: object
properties:
code:
type: string
message:
type: string
'404':
description: Not Found.
content:
application/json:
examples:
message_not_found:
summary: Message not found
value:
code: message_not_found
message: Requested message could not be found.
chat_not_found:
summary: Chat not found
value:
code: chat_not_found
message: The requested chat does not exist or you are not a participant.
schema:
type: object
properties:
code:
type: string
message:
type: string
'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.DELETE
tags:
- messages
/channelsbyname/{CHANNEL_UNIQUE_NAME}/messages:
post:
summary: Post message in a channel with CHANNEL_UNIQUE_NAME
operationId: postMessageInChannelByChannelUniqueName
description: "Use this API to post a message in a channel using its CHANNEL_UNIQUE_NAME.\n
\nYou can also post a message using the following alternative endpoint:
\n\n
\n\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n This limit is per user, not per token — even if messages are sent using multiple OAuth tokens by the same user, all requests count toward this shared limit.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: CHANNEL_UNIQUE_NAME
in: path
description: Unique name of the channel. To learn how to retrieve this ID, see CHANNEL_UNIQUE_NAME in the Glossary page.
required: true
schema:
type: string
example: CHANNEL_UNIQUE_NAME
- name: bot_unique_name
in: query
description: Use this parameter to send a message in a channel as a bot. Note that the bot should already be a participant in the channel.
required: false
schema:
type: string
- name: appkey
in: query
description: 'Extension authentication key. Use this along with bot_unique_name when sending messages as an extension bot.
'
required: false
schema:
type: string
- name: mark_as_read
in: query
description: Use these APIs to mark the sent message as read for the user. By default, the message will be unread for the message posted by the user.
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-a-channel-request'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-a-channel-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:
- messages
/channels/{CHANNEL_ID}/messages:
post:
summary: Post message in a channel with CHANNEL_ID
operationId: postMessageInChannelByChannelId
description: "Use this API to post a message in a channel using its CHANNEL_ID.\n
\nYou can also post a message using the following alternative endpoint:
\n\n
\n\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n This limit is per user, not per token — even if messages are sent using multiple OAuth tokens by the same user, all requests count toward this shared limit.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: CHANNEL_ID
in: path
description: ID of the channel. To learn how to retrieve this ID, see CHANNEL_ID in the Glossary page.
required: true
schema:
type: string
example: CHANNEL_ID
- name: bot_unique_name
in: query
description: Bot identifier for bot-sent messages. The bot must already be a participant in the channel.
required: false
schema:
type: string
pattern: ^[a-z]+$
- name: appkey
in: query
description: Extension authentication key. Use this along with bot_unique_name when sending messages as an extension bot.
required: false
schema:
type: string
- name: mark_as_read
in: query
description: Use these APIs to mark the sent message as read for the user. By default, the message will be unread for the message posted by the user.
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-a-channel-request'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-a-channel-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:
- messages
/chats/{CHAT_ID}/messages:
post:
summary: Post message in chat
operationId: Post message in chat
description: "To post message in a chat (or thread), the chat_id (thread_id in case of threads) can be used in the request URL.\n
\n\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n This limit is per user, not per token — even if messages are sent using multiple OAuth tokens by the same user, all requests count toward this shared limit.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: CHAT_ID
in: path
required: true
schema:
type: string
example: CHAT_ID
description: The ID of the chat where the message should be posted. To learn how to retrieve this ID, see CHAT_ID in the Glossary page.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-chat-request'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/post-message-in-a-chat-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:
- messages
/messages:
post:
summary: Forward Messages
operationId: Forward Messages
description: "Forwards one or more messages from a source chat to other chats or users.\n
\n\n OAuth Scope: ZohoCliq.Messages.CREATE
\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n"
requestBody:
required: true
content:
application/json:
examples:
forward_bug_report:
summary: Forward bug-report messages to QA team and product manager
value:
source:
chat_id: '2890538000000012345'
message_ids:
- '1773813859592_51531973059'
- '1773813860210_51531973060'
recipients:
chat_ids: '2890538000000067890'
user_ids: '70027934'
forward_as_group: true
show_original_sender: true
title: Login Bug - Critical Issue (Forwarded from Engineering)
schema:
$ref: '#/components/schemas/forward-messages-request'
responses:
'200':
description: The request was successfully completed. The response uses a partial-success model. Successfully forwarded IDs appear under forwarded, while per-recipient failures appear in the failures array with specific error details.
content:
application/json:
examples:
partial_success:
summary: Forwarded to QA chat successfully; direct message to PM failed
value:
data:
source_chat_id: '2890538000000012345'
forwarded:
chat_ids:
- '2890538000000067890'
user_ids: []
failures:
- id: '70027934'
status: failed
error:
code: chat_access_denied
message: You must be a participant in this chat to perform this action.
schema:
$ref: '#/components/schemas/forward-messages-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. You do not have permission to read from the source chat or you are not a participant of a recipient chat.
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.
'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.Messages.CREATE
tags:
- messages
/messages/search:
get:
summary: Search Messages
operationId: searchMessagesV3
description: "Search for messages across chats with extensive filtering options. This endpoint supports keyword search, filtering by sender/recipient, date range, file attributes, and more to help you find specific messages efficiently.\n
\n\n Threshold limit: 50 requests per min per user
\n Number of API calls allowed within a minute.
\n Lock period: 10 minutes
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: query
in: query
required: false
schema:
type: string
maxLength: 1000
description: 'Full-text search query to match message content. Supports keywords and phrases (in quotes)
Maximum length: 1000 characters.
'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
default: 50
description: 'Maximum number of messages to return per page. Default is 50, maximum allowed is 50.
'
- name: next_token
in: query
required: false
schema:
type: integer
format: int64
description: 'Pagination cursor returned from a previous response.
Pass the next_token value exactly as received to fetch the next page.
This value is a 64-bit integer cursor.
'
- name: from_user_ids
in: query
required: false
schema:
type: string
description: 'Filter by sender ZUIDs. Provide a comma-separated list of user IDs to restrict results to messages sent by specific users.
Maximum of 5 user IDs allowed.
'
- name: to_user_ids
in: query
required: false
schema:
type: string
description: 'Filter by recipient ZUIDs. Provide a comma-separated list of user IDs to restrict results to messages sent to specific users.
Maximum of 5 user IDs allowed.
'
- name: mentioned_user_ids
in: query
required: false
schema:
type: string
description: 'Filter messages that mention specific users. Provide a comma-separated list of user IDs to find messages that contain mentions of those users.
Maximum of 5 user IDs allowed.
'
- name: chat_ids
in: query
required: false
schema:
type: string
description: 'Filter by chat IDs. Provide a comma-separated list of chat IDs to restrict results to specific chats.
Maximum of 5 chat IDs allowed.
'
- name: chat_type
in: query
required: false
schema:
type: string
description: "Filter by chat type.
\nAllowed values:
\n\n direct_message: One-on-one chats between two users.group_chat: Group chats with multiple participants.channel: Organization-wide or team-specific channels.threads: Threads within channels or group chats.bot: Bot conversation chats.guests: Chats with external guest participants.
\nMaximum of 6 values allowed.\n"
- name: parent_chatid
in: query
required: false
schema:
type: string
description: 'Filter messages within a specific thread by providing the parent chat ID (thread ID). This will return messages that are part of the specified thread.
'
- name: channel_type
in: query
required: false
schema:
type: string
description: "Filter by channel type when searching within channels.
\nAllowed values:
\n\n organisation: Channels that are open to the entire organization.team: Channels that are specific to certain teams.personal: Private channels that are only accessible to invited members.external: Channels that include external users outside the organization.
\n"
- name: team_ids
in: query
required: false
schema:
type: string
description: 'Filter by team IDs when searching within team channels. Provide a comma-separated list of team IDs to restrict results to channels associated with specific teams.
Maximum of 5 team IDs allowed.
'
- name: include_allowed_channels
in: query
required: false
schema:
type: boolean
description: 'When true, include messages from channels that the user has access to, even if they are not explicitly listed in the chat_ids parameter. This allows users to find relevant messages in channels they are part of without needing to specify each channel ID.
'
- name: from_time
in: query
required: false
schema:
type: string
description: 'Start of the date range for the search. Accepts epoch time in milliseconds (Long) or ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Messages sent at or after this time will be included in the results.
'
- name: to_time
in: query
required: false
schema:
type: string
description: 'End of the date range for the search. Accepts epoch time in milliseconds (Long) or ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Note: from_time must be earlier than to_time, otherwise the request fails.
'
- name: file_name
in: query
required: false
schema:
type: string
description: 'Match by file name for messages that contain attachments. Supports partial matches and wildcards (e.g., "report*" to match "report_Q1.pdf"). Accepts a comma-separated list of file names.
Maximum of 10 values allowed. Total maximum length: 500 characters.
'
- name: file_type
in: query
required: false
schema:
type: string
description: 'Filter by file type for messages that contain attachments. Provide a comma-separated list of MIME types (e.g., image/png, application/pdf) to find messages with specific types of attached files.
Maximum of 10 values allowed. Total maximum length: 500 characters.
'
- name: file_content_query
in: query
required: false
schema:
type: string
maxLength: 500
description: 'Full-text search query to match the content of attached files. This allows you to find messages based on the text within attachments, such as documents or PDFs. Supports keywords, phrases (in quotes), and boolean operators (AND, OR, NOT).
Maximum length: 500 characters.
'
- name: message_type
in: query
required: false
schema:
type: string
description: "Filter by message type.
\nAllowed values:
\n\n text: Messages that contain only text content.link: Messages containing URLs.file: Messages that include file attachments.
\n"
- name: is_pinned
in: query
required: false
schema:
type: boolean
description: 'When true, only return messages that are pinned in their respective chats. Note: If this parameter is true, the chat_ids parameter must include exactly one chat ID to specify which chat''s pinned messages to search within.
'
- name: has_mentions
in: query
required: false
schema:
type: boolean
description: 'When true, only return messages that contain mentions of users.
'
- name: star_types
in: query
required: false
schema:
type: string
description: "Filter messages by star types. Provide a comma-separated list of star types to find messages that have been starred with specific types (e.g., \"important,followup\").
\nMaximum of 5 star types allowed.\n
Allowed star types:
\n\n important: Messages marked as requiring attention.to_do: Messages flagged as action items.note: Messages saved for reference.manager: Messages related to managerial communications.follow_up: Messages requiring follow-up.followup: Messages marked for follow-up.question: Messages marked as questions.idea: Messages marked as ideas.other: Messages marked with a custom star type.
\n"
- name: include_bot_messages
in: query
required: false
schema:
type: boolean
description: 'When true, include messages sent by bots in the search results. By default, bot messages are excluded from search results.
'
responses:
'200':
description: The request was successfully completed. Returns a list of matching messages.
content:
application/json:
schema:
$ref: '#/components/schemas/search-messages-response'
examples:
multiple_messages:
summary: Multiple messages found
value:
messages:
- message_id: '1710934200000'
time: '2025-03-20T14:30:00.000Z'
sender: 711622XXXX
chat_id: 6795XXXXXXXXXXXXXX
chat_title: General
type: text
content:
text: Please review the updated proposal.
- message_id: '1710920100000'
time: '2025-03-20T10:35:00.000Z'
sender: 711633XXXX
chat_id: 6795YYYYYYYYYYYY
chat_title: Project Alpha
type: file
content:
file_name: proposal_v2.pdf
file_type: application/pdf
file_size: 204800
channel_type: organisation
next_token: 1710920099000
matched_search_value: proposal
'400':
description: Bad Request. An invalid parameter value was passed.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
invalid_inputs:
summary: Invalid input parameters
value:
error:
code: invalid.inputs.submitted
message: An invalid parameter value was passed. For is_pinned, this also means fewer or more than one chat ID was provided.
invalid_time:
summary: Invalid timestamp
value:
error:
code: invalid.time.submitted
message: Invalid timestamp format or from_time must be earlier than to_time.
'401':
description: Unauthorized. Invalid or missing authentication token.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
unauthorized:
summary: Invalid auth token
value:
error:
code: unauthorized
message: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden. The user is not a member of the organisation.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
invalid_access:
summary: Access denied
value:
error:
code: invalid_access
message: You are not a member of the organisation or do not have permission to access this resource.
'429':
description: Too many requests. Rate limit exceeded.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
rate_limit:
summary: Rate limit exceeded
value:
error:
code: rate_limit_exceeded
message: Too many requests within a certain time frame. Please try again later.
'500':
description: Internal Server Error. An unexpected error occurred while executing the search.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
server_error:
summary: Server error during message search
value:
error:
code: error_message_search
message: An unexpected error occurred while executing the search.
security:
- Cliq_Auth:
- ZohoCliq.Chats.READ
tags:
- messages
components:
schemas:
post-message-in-chat-request:
type: object
description: Request object to send a message in a chat.
required:
- text
properties:
text:
type: string
description: 'Text content to send in chat. Maximum length: 5000.'
maxLength: 5000
example: Hey!
reply_to:
type: string
description: Message ID to reply to in chat.
example: '55743307'
sync_message:
type: boolean
description: Post message in synchronous thread; returns message ID.
example: true
mark_as_read:
type: boolean
description: Mark the message as read for the user.
example: true
post-message-in-a-channel-request:
type: object
description: Request object to post a message in a channel.
required:
- text
properties:
text:
type: string
description: 'Message text to be sent in the channel. Maximum length: 5000.'
maxLength: 5000
example: Hello team, please review the project status update and share your feedback by EOD.
reply_to:
type: string
description: Message ID to reply to in the channel.
example: '72374289911'
sync_message:
type: boolean
description: Whether to post the message in a synchronous thread.
example: true
post-message-in-a-chat-response:
type: object
description: Response object for posting messages in a chat/user
properties:
message_id:
type: string
description: Unique identifier of the newly posted message
example: '1599387839188_229293271789'
forward-messages-response:
type: object
description: Response object after forwarding messages. Uses a partial-success model.
properties:
data:
type: object
description: Forwarding results data.
properties:
source_chat_id:
type: string
description: Source chat ID from which messages were forwarded.
example: C_987654321
forwarded:
type: object
description: Successfully forwarded recipients.
properties:
chat_ids:
type: array
description: List of chat IDs where messages were successfully forwarded.
items:
type: string
example:
- C_111111111
user_ids:
type: array
description: List of user IDs to whom messages were successfully forwarded.
items:
type: string
example:
- '60025012345'
failures:
type: array
description: List of per-recipient failures with specific error details.
items:
type: object
properties:
id:
type: string
description: Chat ID or user ID that failed.
example: C_222222222
status:
type: string
description: Status of the forward attempt.
example: failed
error:
type: object
description: Error details for the failure.
properties:
code:
type: string
description: Error code.
example: chat_with_other_org_users_disabled
message:
type: string
description: Error message.
example: Chat with other org users is disabled
post-message-in-a-channel-response:
type: object
description: Response object after posting a message in a channel.
properties:
Response Code:
type: string
description: HTTP response code for the operation.
example: 204 No response
forward-messages-request:
type: object
description: Request object to forward one or more messages from a source chat to other chats or users.
required:
- source
- recipients
properties:
source:
type: object
description: 'Source chat and messages to forward. You can specify 1 to 25 message IDs from a single chat to forward in one request.
'
required:
- chat_id
- message_ids
properties:
chat_id:
type: string
description: 'Chat ID from which messages will be forwarded. All message IDs must belong to this chat.
'
example: C_987654321
message_ids:
type: array
description: 'List of message IDs to forward. All messages must be from the same source chat specified by chat_id. You can forward a minimum of 1 message and a maximum of 25 messages in a single request.
'
minItems: 1
maxItems: 25
items:
type: string
example:
- '1742000000000001'
- '1742000000000002'
recipients:
type: object
description: 'Recipients to forward the messages to. You can specify up to 100 chat IDs and/or user IDs as recipients. Messages will be forwarded to all specified recipients based on the provided options.
'
properties:
chat_ids:
type: string
description: 'Comma-separated list of chat IDs to forward messages to.
Maximum of 100 chat IDs allowed.
'
example: C_111111111,C_222222222
user_ids:
type: string
description: 'Comma-separated list of user IDs to forward messages to.
Maximum of 100 user IDs allowed.
'
example: 60025012345,60025012346
forward_as_group:
type: boolean
description: 'When true, messages will be forwarded as a single combined message in the recipient chats, rather than individual messages. The content of the forwarded message will include all original messages grouped together. If false or not provided, each message will be forwarded separately in the recipient chats.
Note: If forwarding to multiple recipients, it''s recommended to set this to true to avoid spamming recipients with multiple messages.
'
example: false
show_original_sender:
type: boolean
description: 'When true, the forwarded message will include the name of the original sender for each message. This is applicable when forward_as_group is true to provide context about who sent each message in the group forward. If false or not provided, the original sender''s name will not be displayed in the forwarded message content.
'
example: true
title:
type: string
description: 'Optional title to include with the forwarded message when forward_as_group is true. This title will be displayed at the top of the grouped forwarded message in the recipient chats. If not provided, no title will be shown.
Maximum length: 255 characters.
'
maxLength: 255
example: Group Title 1
search-messages-response:
type: object
description: Response object for message search results containing matching messages and pagination information.
properties:
messages:
type: array
description: List of messages matching the search criteria.
items:
type: object
properties:
message_id:
type: string
description: Unique identifier (timestamp) of the message.
example: '1710934200000'
time:
type: string
format: date-time
description: When the message was sent (ISO 8601 format).
example: '2025-03-20T14:30:00.000Z'
sender:
type: string
description: ZUID of the user who sent the message.
example: 711622XXXX
chat_id:
type: string
description: ID of the chat the message belongs to.
example: 6795XXXXXXXXXXXXXX
chat_title:
type: string
description: Display name of the chat.
example: General
type:
type: string
description: 'Message type: text, file, link, etc.'
example: text
enum:
- text
- file
- link
- card
- table
- slides
- form
- poll
- audio
- video
- image
content:
type: object
description: Message content - structure varies by type.
additionalProperties: true
properties:
text:
type: string
description: Text content of the message (for text type messages).
example: Please review the updated proposal.
file_name:
type: string
description: Name of the file (for file type messages).
example: proposal_v2.pdf
file_type:
type: string
description: MIME type of the file.
example: application/pdf
file_size:
type: integer
description: Size of the file in bytes.
example: 204800
channel_type:
type: string
description: 'Present for channel messages: organisation, team, personal, external.'
example: organisation
enum:
- organisation
- team
- personal
- external
channel_unique_id:
type: string
description: Unique permalink identifier of the channel, if applicable.
star_type:
type: string
description: Star label on the message, if any.
enum:
- important
- to_do
- note
- manager
- follow_up
reply_message_id:
type: string
description: ID of the message being replied to, if this is a reply.
parent_chat_id:
type: string
description: For thread messages - the ID of the parent chat.
parent_chat_title:
type: string
description: For thread messages - the display name of the parent chat.
thread_message_id:
type: string
description: For thread messages - the ID of the thread head message.
thread_state:
type: string
description: For thread messages - the state of the thread.
next_token:
type: integer
format: int64
description: Pass this in the next request to fetch the following page of results. Absent when there are no more results.
example: 1710920099000
matched_search_value:
type: string
description: The query value that was searched. Included when query was provided.
example: proposal
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/