openapi: 3.0.0
info:
title: Bots threads 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: threads
description: Threads Module
paths:
/channels/{CHANNEL_ID}/messages:
post:
summary: Create and send a thread message with CHANNEL_ID
operationId: createThreadMessageByChannelId
description: "Use this API to create a thread from a message sent in a channel, identified by its CHANNEL_ID.
You can also create a thread using one of the following alternative endpoints:
Note: The channel's reply mode must be set to Threads or Allow both for thread creation to work. See Configuring Reply Mode for Channels for more details. \n Threshold limit: 20 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: CHANNEL_ID
in: path
required: true
schema:
type: string
example: CHANNEL_ID
description: The unique identifier of the channel in which the thread needs to be created. To learn how to retrieve this ID, see CHANNEL_ID in the Glossary page.
- name: bot_unique_name
in: query
required: false
schema:
type: string
description: 'Use this parameter to send a message in a channel as a bot. Note: The bot should already be a participant in the channel.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-payload'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-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:
- threads
/chats/{CHAT_ID}/messages:
post:
summary: Create and send a thread message with CHAT_ID
operationId: createThreadMessageByChatId
description: "Use this API to create a thread from a message sent in a channel, identified by its CHAT_ID. Every channel in Cliq also has a corresponding chat ID. This endpoint is functionally equivalent to using POST /channels/{CHANNEL_ID}/messages - both target the same channel, just identified differently.
You can also create a thread using one of the following alternative endpoints:
Note: The channel's reply mode must be set to Threads or Allow both for thread creation to work. See Configuring Reply Mode for Channels for more details. \n Threshold limit: 20 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: CHAT_ID
in: path
required: true
schema:
type: string
example: CHAT_ID
description: The chat ID of the channel in which the thread needs to be created. Every channel has a corresponding chat ID. To learn how to retrieve this ID, see CHAT_ID in the Glossary page.
- name: bot_unique_name
in: query
required: false
schema:
type: string
description: 'Use this parameter to send a message in a channel as a bot. Note: The bot should already be a participant in the channel.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-payload'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-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:
- threads
/channelsbyname/{CHANNEL_UNIQUE_NAME}/messages:
post:
summary: Create and send a thread message with CHANNEL_UNIQUE_NAME
operationId: createThreadMessageByChannelUniqueName
description: "Use this API to create a thread from a message sent in a channel, identified by its unique name. This is useful when you know the channel's unique name but not its ID.
You can also create a thread using one of the following alternative endpoints:
Note: The channel's reply mode must be set to Threads or Allow both for thread creation to work. See Configuring Reply Mode for Channels for more details. \n Threshold limit: 20 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: CHANNEL_UNIQUE_NAME
in: path
required: true
schema:
type: string
example: CHANNEL_UNIQUE_NAME
description: The unique name of the channel in which the thread needs to be created. To learn how to retrieve this, see CHANNEL_UNIQUE_NAME in the Glossary page.
- name: bot_unique_name
in: query
required: false
schema:
type: string
description: 'Use this parameter to send a message in a channel as a bot. Note: The bot should already be a participant in the channel.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-payload'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-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:
- threads
/chats/{THREAD_CHAT_ID}/messages:
post:
summary: Send a message to an existing thread
operationId: Send a message to an existing thread
description: "Use this API to send a message to an existing thread.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: Chat ID of the thread where the message should be sent. To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
- name: bot_unique_name
in: query
required: false
schema:
type: string
description: 'Use this parameter to send a message in a thread as a bot. Note that the bot should already be a participant in the channel.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/send-message-in-thread-payload'
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/thread-creation-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:
- threads
/threads/{THREAD_CHAT_ID}:
put:
summary: Update the state of a thread
operationId: Update the state of a thread
description: "Use this API to update the state or follow status of a thread.\n\n - Thread state: Close a thread to stop further replies, or reopen it to resume discussion.
\n - Follow state: Follow a thread to receive notifications for new replies, or unfollow to stop them.
\n
\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: CHAT ID of the thread whose state is to be updated (closed or reopened). To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
- name: bot_unique_name
in: query
required: false
schema:
type: string
description: To use when the action is to be performed by a bot that is already a participant in the channel.
- name: appkey
in: query
required: false
schema:
type: string
description: Must be provided if the specified bot is from an extension. This parameter is to be used along with bot_unique_name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update-state-of-thread-request'
responses:
'204':
description: The request was successfully completed. No content is returned.
'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.Chats.UPDATE
tags:
- threads
/threads/{THREAD_CHAT_ID}/messages/main:
get:
summary: Get main message of a thread
operationId: Get main message of a thread
description: "Use this API to retrieve the main message from which the thread was created.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: The CHAT_ID of the thread whose main (original) message is to be retrieved To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
examples:
main_thread_message:
summary: Main message for a customer escalation thread
value:
parent_resource_id: engineering-updates
sender:
name: Ryan West
id: '855727961'
mentions:
- name: '@Scott Fisher'
id: '855727962'
type: user
- name: '@Tim Harrison'
id: '855727963'
type: user
thread_information:
thread_message_id: 1760000012345%201234567890
title: Customer onboarding latency issue
follower_count: 3
message_count: 18
chat_id: CT_2242125513190139257_855711548-T-2263887074117538898
id: '1760000012345_1234567890'
time: '2026-05-28T10:36:48+00:00'
thread_state_information:
thread_state: open
type: text
content:
text: The customer onboarding workflow is intermittently delayed. Please share logs and mitigation updates in this thread.
is_pinned: false
schema:
$ref: '#/components/schemas/get-main-message-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.Messages.READ
tags:
- threads
/threads/{THREAD_CHAT_ID}/followers:
get:
summary: Get thread followers
operationId: Get thread followers
description: 'Use this API to get the followers of the thread.
'
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: Chat ID of the thread for which the list of followers needs to be retrieved To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
examples:
followers_list:
summary: Thread followers in Zylker
value:
data:
- user_id: '855727961'
email_id: ryan.west@zylker.com
name: Ryan West
- user_id: '855727962'
email_id: scott.fisher@zylker.com
name: Scott Fisher
schema:
$ref: '#/components/schemas/get-thread-followers-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.Chats.READ
tags:
- threads
post:
summary: Add followers to a thread
operationId: Add followers to a thread
description: "Use this API to add one or more users as followers to an existing thread.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: Chat ID of the thread for which the list of followers needs to be added To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/add-followers-payload'
responses:
'204':
description: The request was successfully completed. No content is returned.
'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.Chats.UPDATE
tags:
- threads
delete:
summary: Remove followers from a thread
operationId: Remove followers from a thread
description: "Removes one or more specified users from the followers list of a given thread.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: Chat ID of the thread for which the list of followers needs to be removed To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/remove-followers-payload'
responses:
'204':
description: The request was successfully completed. No content is returned.
'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.Chats.DELETE
tags:
- threads
/threads/{THREAD_CHAT_ID}/nonfollowers:
get:
summary: Get non-followers of a thread
operationId: Get non-followers of a thread
description: "Use this API to retrieve the list of channel members who are not currently following the specified thread.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: Chat ID of the thread for which the list of non-followers needs to be retrieved To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
examples:
nonfollowers_list:
summary: Channel members not following the thread
value:
data:
- user_id: '855727963'
email_id: tim.harrison@zylker.com
name: Tim Harrison
schema:
$ref: '#/components/schemas/get-thread-followers-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.Chats.READ
tags:
- threads
/threads/{THREAD_CHAT_ID}/follow:
post:
summary: Join (follow) a thread
operationId: Join-follow a thread
description: "Allows the authenticated user to join a thread as a follower.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: CHAT ID of the thread to which the authenticated user should be added as a follower To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'204':
description: The request was successfully completed. No content is returned.
'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.Chats.UPDATE
tags:
- threads
/threads/{THREAD_CHAT_ID}/unfollow:
post:
summary: Leave (unfollow) a thread
operationId: Leave-unfollow a thread
description: "Allows the authenticated user to leave a thread they are currently following.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: CHAT ID of the thread to which the authenticated user should be removed as a follower To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'204':
description: The request was successfully completed. No content is returned.
'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.Chats.UPDATE
tags:
- threads
/chats/{THREAD_CHAT_ID}/members:
get:
summary: Retrieve members of a thread
operationId: Retrieve members of a thread
description: "Use this API to fetch participants of a specific thread conversation.\nThis is useful when you want to display who is currently involved in a focused topic discussion without scanning the parent channel.\n
\nCommon use cases:\n\n - Render a thread participant panel in your app UI.
\n - Show participant identity fields (name, email_id, user_id) using the
fields query parameter. \n - Audit collaboration context before automations post follow-up replies in the same thread.
\n
\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: The ID of the thread from which members need to be retrieved. To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
- name: fields
in: query
required: false
schema:
type: string
description: "Use this parameter to get details of members participating in the thread.
\nAllowed values:\n\n - user_id - Unique identifier for the user in Cliq.
\n - email_id - Email address of the user.
\n - name - Display name of the user.
\n
\n
\n"
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/retrieve-chat-members'
'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.Chats.READ
tags:
- threads
/chats/{THREAD_CHAT_ID}/leave:
post:
summary: Leave a thread
operationId: Leave a thread
description: "Use this API to remove the authenticated user from a thread conversation.\nAfter leaving, the user is no longer an active participant in that thread context.\n
\nThis endpoint is helpful for reducing noise in discussions that are no longer relevant to the user while keeping the parent channel membership unchanged.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: The ID of the thread that you wish to leave. To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/no-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.Chats.UPDATE
tags:
- threads
/chats/{THREAD_CHAT_ID}/mute:
post:
summary: Mute a thread
operationId: Mute a thread
description: "Use this API to mute notifications for a thread while still keeping the thread accessible.\nMuting is ideal for high-volume threads where the user wants to stay in the conversation but avoid immediate notification interruptions.\n
\nThis setting affects thread-level notifications and helps keep topic-based discussions organized without muting the entire parent chat.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: The ID of the thread that needs to be muted. To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/no-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.Chats.UPDATE
tags:
- threads
/chats/{THREAD_CHAT_ID}/unmute:
post:
summary: Unmute a thread
operationId: Unmute a thread
description: "Use this API to restore notifications for a previously muted thread.\nOnce unmuted, the user starts receiving thread updates again according to their notification settings.\n
\nUse this when a discussion becomes active or relevant again and timely visibility of thread replies is required.\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
Wait time before consecutive API requests.
\n
\n"
parameters:
- name: THREAD_CHAT_ID
in: path
required: true
schema:
type: string
example: THREAD_CHAT_ID
description: The ID of the thread that needs to be unmuted. To learn how to retrieve this ID, see THREAD_CHAT_ID in the Glossary page.
responses:
'200':
description: The request was successfully completed.
content:
application/json:
schema:
$ref: '#/components/schemas/no-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.Chats.UPDATE
tags:
- threads
components:
schemas:
send-message-in-thread-payload:
type: object
description: Request body to send a message in an existing thread.
required:
- text
properties:
text:
type: string
description: 'Text to post in the thread. Maximum length: 5000 characters.'
example: Let's automate these cases so we can address them during testing.
reply_to:
type: string
description: Optional. Message ID to reply to within the thread.
post_in_parent:
type: boolean
description: Optional. If true, posts the message in the parent chat as well.
example: true
sync_message:
type: boolean
description: Optional. If true, posts the message synchronously and returns the message ID.
example: true
retrieve-chat-members:
type: object
description: Response object containing members of a chat.
properties:
members:
type: array
description: List of members in the chat with detailed user information.
items:
$ref: '#/components/schemas/Members'
thread-creation-response:
type: object
description: Response returned after creating a thread.
properties:
message_id:
type: string
description: ID of the created thread message.
example: '1275417686584_20804595296'
no-response:
type: object
description: Response object returned when no content is available.
properties:
Response Code:
type: string
description: HTTP response code and message indicating no content.
example: 204 No response
get-main-message-response:
type: object
description: Response containing the details of a main message and its thread information.
properties:
parent_resource_id:
type: string
description: Resource ID of the parent entity.
example: engineering-updates
sender:
type: object
description: Information about the sender of the message.
properties:
name:
type: string
example: Ryan West
id:
type: string
example: '855727961'
mentions:
type: array
items:
type: object
properties:
name:
type: string
example: '@Scott Fisher'
id:
type: string
example: '855727962'
type:
type: string
example: user
thread_information:
type: object
description: Additional thread information.
properties:
thread_message_id:
type: string
example: 1760000012345%201234567890
title:
type: string
example: Customer onboarding latency issue
follower_count:
type: integer
example: 3
message_count:
type: integer
example: 18
chat_id:
type: string
example: CT_2242125513190139257_855711548-T-2263887074117538898
id:
type: string
example: '1760000012345_1234567890'
time:
type: string
format: date-time
example: '2026-05-28T10:36:48+00:00'
thread_state_information:
type: object
description: State information of the thread.
properties:
thread_state:
type: string
example: open
type:
type: string
example: text
content:
type: object
properties:
text:
type: string
example: The customer onboarding workflow is intermittently delayed. Please share logs and mitigation updates in this thread.
is_pinned:
type: boolean
example: false
add-followers-payload:
type: object
description: Request body to add followers to a thread.
required:
- user_ids
properties:
user_ids:
type: array
description: List of user IDs to add as followers to the thread.
items:
type: string
description: Unique identifier of a user to be added as a follower.
example:
- '15067889'
- '35068981'
- '5120923'
thread-creation-payload:
type: object
description: Request body to create a new thread from an existing message.
required:
- text
- thread_message_id
properties:
text:
type: string
description: 'Text to post as the initial message in the thread. Maximum length: 5000 characters.'
example: Follow this thread for daily updates on ticket resolutions.
thread_message_id:
type: string
description: ID of the parent message from which the thread should be created.
example: '1599044334698_117280617320'
reply_to:
type: string
description: Optional. ID of a message to reply to within the thread.
post_in_parent:
type: boolean
description: Optional. If true, posts the thread message in the parent chat as well.
example: true
thread_title:
type: string
description: Optional. Title for the thread.
example: Ticket Resolution Summary for the Day
sync_message:
type: boolean
description: Optional. If true, posts the message synchronously and returns the message ID.
example: true
get-thread-followers-response:
type: object
description: Response containing the list of followers for a particular thread.
properties:
data:
type: array
description: List of users following the thread.
items:
type: object
properties:
user_id:
type: string
description: Unique identifier of the user.
example: '855727961'
email_id:
type: string
format: email
description: Email ID of the user.
example: ryan.west@zylker.com
name:
type: string
description: Name of the user.
example: Ryan West
example:
- user_id: '855727961'
email_id: ryan.west@zylker.com
name: Ryan West
- user_id: '855727962'
email_id: scott.fisher@zylker.com
name: Scott Fisher
- user_id: '855727963'
email_id: tim.harrison@zylker.com
name: Tim Harrison
update-state-of-thread-request:
type: object
description: Request body to update the state of a thread (open or closed).
required:
- action
properties:
action:
type: string
description: "Action to update the thread state.
\nAllowed values:
\n \n - reopen - Reopen a closed thread.
\n - close - Close an open thread to prevent new messages from being added.
\n - follow - Follow the thread to receive notifications for new messages.
\n - unfollow - Unfollow the thread to stop receiving notifications for new messages.
\n
\n"
example: close
remove-followers-payload:
type: object
description: Request body to remove followers from a thread.
required:
- user_ids
properties:
user_ids:
type: array
description: List of user IDs to remove from followers of the thread.
items:
type: string
description: Unique identifier of a user to be removed from the thread.
example:
- '15067889'
- '35068981'
- '5120923'
Members:
type: object
description: Detailed information about a chat member.
properties:
user_id:
type: string
description: Unique identifier of the user.
example: '431930546'
email_id:
type: string
format: email
description: Email address of the user.
example: olivia.palmer@zylcal.com
name:
type: string
description: Full name of the user.
example: Olivia - Content Writer
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/