openapi: 3.0.0
info:
title: Bots Stars 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: Stars
paths:
/stars:
post:
summary: Star a Message or Update Star Type
operationId: star_a_message
description: "Stars a message with a specific star type. This enables users to categorize messages for easier retrieval and workflow management. Each message can have only one active star type at a time.\n
\nIf the message is already starred, this operation updates the existing star type to the newly specified type and hence no separate update call is needed. \nWhen the star type is updated, the response includes star_information.old_star_type indicating the previous star type.\n
\n\n OAuth Scope: Messages
\n Threshold limit: 50 requests per min
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests after exceeding the threshold.
\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 | input_invalid | \n Missing or invalid input parameters. | \n
\n \n | chat_not_found | \n The specified chat does not exist or cannot be accessed. | \n
\n \n | operation_failed | \n The operation could not be completed due to a server-side issue. | \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"
requestBody:
description: Provide the chat ID, message ID, and the star type to categorize the message. To update an existing star type, send the same fields with the new star type - the API will automatically update it.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StarMessageRequest'
examples:
star_a_message:
summary: Star a message
value:
chat_id: CT_1894736520184930172_847291635
message_id: '1746000123456789001'
star_type: important
update_star_type:
summary: Update star type of an already-starred message
value:
chat_id: CT_1894736520184930172_847291635
message_id: '1746000123456789001'
star_type: follow_up
responses:
'200':
description: Message starred successfully. If the message was already starred, the star type has been updated and the previous type is returned in `star_information.old_star_type`.
content:
application/json:
schema:
$ref: '#/components/schemas/StarMessageResponse'
examples:
star_a_message:
summary: Message starred for the first time
value:
type: text
id: '1746000123456789001'
time: '2026-04-30T10:00:00Z'
sender:
id: '1234567890'
name: Alice Johnson
content:
text: Please review the Q2 report before Friday.
is_pinned: false
star_information:
star_type: important
starred_message_time: '2026-04-30T10:15:30Z'
chat_information:
chat_id: CT_1894736520184930172_847291635
chat_type: chat
title: Alice Johnson
joined: true
update_star_type:
summary: Star type updated - old_star_type shows the previous type
value:
type: text
id: '1746000123456789001'
time: '2026-04-30T10:00:00Z'
sender:
id: '1234567890'
name: Alice Johnson
content:
text: Please review the Q2 report before Friday.
is_pinned: false
star_information:
star_type: follow_up
starred_message_time: '2026-04-30T10:15:30Z'
old_star_type: important
chat_information:
chat_id: CT_1894736520184930172_847291635
chat_type: chat
title: Alice Johnson
joined: true
'400':
description: Bad Request. Missing or invalid parameters submitted.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1012
message:
type: string
example: input_invalid
example:
code: 1012
message: input_invalid
'401':
description: Unauthorized. Request was rejected due to invalid authentication token.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden. User does not have sufficient permissions to access this resource.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not a user of the respective organization to access the resource.
'404':
description: Not Found. The specified message or chat does not exist or user cannot access it.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 11016
message:
type: string
example: chat_not_found
examples:
chat_not_found:
value:
code: 11016
message: chat_not_found
summary: Chat does not exist or user cannot access it
'429':
description: Too Many Requests. Rate limit exceeded.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error. Unexpected error during star operation.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1011
message:
type: string
example: operation_failed
example:
code: 1011
message: operation_failed
security:
- Cliq_Auth:
- ZohoCliq.Messages.CREATE
tags:
- Stars
get:
summary: List starred messages
operationId: list_starred_messages
description: "Retrieves the authenticated user's starred messages with support for advanced filtering, cursor-based pagination, and incremental synchronization.\n
\nThis endpoint allows you to filter starred messages by chat, star type, and time range. Use pagination tokens to navigate through large result sets efficiently.\n
\n\n OAuth Scope: Messages
\n Threshold limit: 30 requests per min
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests after exceeding the threshold.
\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 | input_invalid | \n Invalid filter inputs were provided. | \n
\n \n | chat_access_denied | \n You are not authorized to access one or more requested chats. | \n
\n \n | operation_failed | \n The operation could not be completed due to a server-side issue. | \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: query
required: false
description: 'Filter starred messages to only include those from a specific chat. Provide the chat ID in the format "2000000012345_2000000067890". If omitted, starred messages from all chats will be included.
'
schema:
type: string
example: '2000000012345_2000000067890'
- name: star_type
in: query
required: false
description: "Filter starred messages by a specific star type.\n
\n Allowed values:
\n \n important: Mark messages that require special attention or contain critical information.to_do: Flag messages representing tasks or action items that need to be completed.note: Save messages for future reference or as reminders of important information.manager: Highlight messages related to managerial communications or approvals.follow_up: Identify messages that require follow-up actions or responses.all: Retrieve all starred messages regardless of star type.
\n"
schema:
type: string
enum:
- important
- to_do
- note
- manager
- follow_up
- all
example: important
- name: from_time
in: query
required: false
description: '
- Lower bound timestamp for message time.
- Accepts epoch milliseconds (for example,
1704067200000) or ISO 8601 datetime strings (for example, 2024-01-01T00:00:00Z).
- Only messages starred after this time will be included in the results.
- If omitted, there is no lower time limit on the messages returned.
'
schema:
type: string
example: '1704067200000'
- name: to_time
in: query
required: false
description: '
- Upper bound timestamp for message time.
- Accepts epoch milliseconds (for example,
1735689599999) or ISO 8601 datetime strings (for example, 2024-12-31T23:59:59Z).
- Only messages starred before this time will be included in the results.
- If omitted, there is no upper time limit on the messages returned.
'
schema:
type: string
example: '1735689599999'
- name: limit
in: query
required: false
description: 'Maximum number of starred messages to return in the response.
Maximum limit:50
Default:50
If the total number of starred messages exceeds this limit, a pagination token will be included in the response to retrieve the next page of results.
'
schema:
type: integer
minimum: 1
maximum: 50
default: 50
example: 25
- name: next_token
in: query
required: false
description: "Opaque pagination token to retrieve the next page of results.\n\n - This token is provided in the response when there are more results available than can fit in a single response.
\n - To retrieve the next page, include this token in the subsequent request without modifying it.
\n - The token is base64-encoded.
\n - If omitted, the first page of results will be returned.
\n
\n"
schema:
type: string
example: ey5MDUzODAwMDAwMDAxMjM0NSIsInRpbWVzdGFtcCI6MTcxNDkyMDQwMDAwMH0=
- name: sync_token
in: query
required: false
description: "Synchronization token for incremental updates.\n\n - This token is returned in the response to help clients sync local state.
\n - When provided in a request, only starred message changes after that sync point are returned.
\n - If omitted, results are returned based on the other filters.
\n - Format: base64 token.
\n - Maximum length: 200 characters.
\n
\n"
schema:
type: string
maxLength: 200
example: 911083u18u3811834u
responses:
'200':
description: Starred messages retrieved successfully.
content:
application/json:
examples:
starred_messages:
summary: List of starred messages with next_token
value:
star_messages:
- type: text
id: '1746000123456789001'
time: '2026-04-30T10:00:00Z'
sender:
id: '1234567890'
name: Alice Johnson
content:
text: Please review the Q2 report before Friday.
is_pinned: false
star_information:
star_type: important
starred_message_time: '2026-04-30T10:15:30Z'
chat_information:
chat_id: chid_abcdef123456
chat_type: chat
title: Alice Johnson
joined: true
- type: file
id: '1746000987654321002'
time: '2026-04-30T09:40:00Z'
sender:
id: '9876543210'
name: Bob Smith
content:
file_name: Q2_Report_Final.pdf
file_size: 204800
file_url: https://cliq.zoho.com/file/download?id=enc_file_id_xyz
is_pinned: false
star_information:
star_type: to_do
starred_message_time: '2026-04-30T09:45:00Z'
chat_information:
chat_id: chid_channel_org_001
chat_type: channel
title: Engineering Announcements
display_name: Engineering Announcements
joined: true
next_token: eyJsYXN0U3RhcnJlZFRpbWUiOiIxNzQ1OTkwMDAwMDAwIiwibGltaXQiOjJ9
schema:
type: object
properties:
type:
type: string
example: star_messages
next_token:
type: string
description: Opaque base64-encoded pagination token for the next page. Omitted if no more pages exist.
example: asdhfqjdbnajdndjnadj
sync_token:
type: string
description: Synchronization token for incremental updates.
example: 911083u18u3811834u
data:
type: array
description: Array of starred messages in V3 message hash format.
items:
type: object
properties:
star_information:
type: object
properties:
star_type:
type: string
example: important
starred_message_time:
type: string
format: date-time
example: '2026-03-25T10:30:00.000Z'
file_permission:
type: object
properties:
cross_org_policy:
type: boolean
example: true
file_scope:
type: string
example: '60005678901'
chat_information:
type: object
properties:
chat_id:
type: string
example: '2000000012345_2000000067890'
chat_type:
type: string
example: direct
title:
type: string
example: John Doe
display_name:
type: string
example: John Doe
joined:
type: boolean
example: true
receiver:
type: string
example: '2000000012345'
'400':
description: Bad Request. Query parameter validation failed.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1012
message:
type: string
example: input_invalid
'401':
description: Unauthorized. Request was rejected due to invalid authentication token.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden. User is not a participant of the specified chat.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 430002
message:
type: string
example: chat_access_denied
example:
code: 430002
message: chat_access_denied
'429':
description: Too Many Requests. Rate limit exceeded.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error. Unexpected error occurred during retrieval.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1011
message:
type: string
example: operation_failed
security:
- Cliq_Auth:
- ZohoCliq.Messages.READ
tags:
- Stars
/stars/{MESSAGE_ID}:
delete:
summary: Unstar a Message
operationId: unstar_a_message
description: "Removes the star from a specified message. This operation permanently deletes the star record for the authenticated user.\n
\nIf the message is not currently starred by the user, an error will be returned.\n
\n\n OAuth Scope: Messages
\n Threshold limit: 50 requests per min
\n Number of API calls allowed within a minute.
\n Lock period: 5 minutes
Wait time before consecutive API requests after exceeding the threshold.
\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 | input_invalid | \n Missing or invalid message identifier. | \n
\n \n | star_not_found | \n The message is not currently starred for the user. | \n
\n \n | operation_failed | \n The operation could not be completed due to a server-side issue. | \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: MESSAGE_ID
in: path
required: true
description: 'The unique identifier of the message to be unstarred.
Use the Retrieve Starred Messages endpoint to get the message IDs of starred messages.
'
schema:
type: string
example: MESSAGE_ID
responses:
'204':
description: Message unstarred successfully. No content returned.
'400':
description: Bad Request. Missing or invalid message ID.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1012
message:
type: string
example: input_invalid
example:
code: 1012
message: input_invalid
'401':
description: Unauthorized. Request was rejected due to invalid authentication token.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Request was rejected because of invalid AuthToken.
'403':
description: Forbidden. User does not have sufficient permissions to access this resource.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The user does not have enough permission or possibly not a user of the respective organization to access the resource.
'404':
description: Not Found. Star record not found for the current user.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 8004
message:
type: string
example: star_not_found
example:
code: 8004
message: star_not_found
'429':
description: Too Many Requests. Rate limit exceeded.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Too many requests within a certain time frame.
'500':
description: Internal Server Error. Unexpected error during unstar operation.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1011
message:
type: string
example: operation_failed
example:
code: 1011
message: operation_failed
security:
- Cliq_Auth:
- ZohoCliq.Messages.DELETE
tags:
- Stars
components:
schemas:
StarMessageResponse:
type: object
properties:
type:
type: string
example: text
id:
type: string
description: The unique identifier of the message.
example: '1746000123456789001'
time:
type: string
format: date-time
description: The timestamp when the message was sent (ISO 8601 format).
example: '2026-04-30T10:00:00Z'
sender:
type: object
properties:
id:
type: string
example: '1234567890'
name:
type: string
example: Alice Johnson
content:
type: object
properties:
text:
type: string
example: Please review the Q2 report before Friday.
is_pinned:
type: boolean
example: false
star_information:
$ref: '#/components/schemas/StarInformation'
chat_information:
$ref: '#/components/schemas/ChatInformation'
example:
type: text
id: '1746000123456789001'
time: '2026-04-30T10:00:00Z'
sender:
id: '1234567890'
name: Alice Johnson
content:
text: Please review the Q2 report before Friday.
is_pinned: false
star_information:
star_type: important
starred_message_time: '2026-04-30T10:15:30Z'
chat_information:
chat_id: CT_1894736520184930172_847291635
chat_type: chat
title: Alice Johnson
joined: true
StarInformation:
type: object
description: Information about the star applied to a message.
properties:
star_type:
type: string
description: The category of the star.
enum:
- important
- to_do
- note
- manager
- follow_up
example: important
old_star_type:
type: string
description: The previous star type if the message was already starred (returned only on updates).
example: note
starred_message_time:
type: string
format: date-time
description: The timestamp when the message was starred (ISO 8601 format).
example: '2026-03-25T10:30:00.000Z'
file_permission:
type: object
description: File permissions associated with the starred message (if applicable).
properties:
cross_org_policy:
type: boolean
description: Indicates if cross-organization access is allowed.
example: true
file_scope:
type: string
description: The scope identifier for file access.
example: '60005678901'
StarMessageRequest:
type: object
required:
- chat_id
- message_id
- star_type
properties:
chat_id:
type: string
description: The unique identifier of the chat containing the message to be starred.
example: CT_1894736520184930172_847291635
message_id:
type: string
description: The unique identifier of the message to be starred.
example: '1746000123456789001'
star_type:
type: string
description: "The category of the star to apply to the message. This determines how the message will be organized and retrieved in starred messages lists.\n
\nAllowed values:
\n\n important: Mark messages that require special attention or contain critical information.to_do: Flag messages representing tasks or action items that need to be completed.note: Save messages for future reference or as reminders of important information.manager: Highlight messages related to managerial communications or approvals.follow_up: Identify messages that require follow-up actions or responses.
\n"
enum:
- important
- to_do
- note
- manager
- follow_up
example: important
ChatInformation:
type: object
description: Information about the chat containing the starred message.
properties:
chat_id:
type: string
description: The unique identifier of the chat.
example: '2000000012345_2000000067890'
chat_type:
type: string
description: The type of chat (e.g., direct, channel, group).
example: direct
title:
type: string
description: The title of the chat.
example: John Doe
display_name:
type: string
description: The display name shown for the chat.
example: John Doe
joined:
type: boolean
description: Indicates if the user has joined the chat.
example: true
receiver:
type: string
description: The user ID of the message receiver (for direct chats).
example: '2000000012345'
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/