openapi: 3.0.0 info: title: Bots mypins 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

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.
When the trigger event occurs, the corresponding handler executes it's script to perform actions like sending messages, making API calls, or updating data.
By configuring different handlers, you can create bots that respond intelligently to various user interactions and automate complex workflows within Zoho Cliq.

Types of Bot Handlers

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Handler	Description
Menu Handler	Adds up to 5 quick-action items to the bot's chat menu. Triggered when a user interacts with the menu.
Message Handler	Triggered when the bot receives a message.
Welcome Handler	Defines the greeting message sent when a user subscribes to the bot.
Mention Handler	Triggered when the bot is @mentioned in a chat or channel.
Incoming Webhook Handler	Allows external services to post messages into the bot via outgoing webhooks.
Context Handler	Manages multi-turn conversations, maintaining context across a user's interaction with the bot.

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.

If execution_type is not specified during bot creation, it defaults to deluge.
Handler logic is defined as a script field (Deluge source code) when creating or updating handlers.
Suitable for teams that want to build and manage bot logic entirely within Zoho's ecosystem.

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.

To create a Webhook bot, set execution_type to webhook during bot creation and provide the execution_url where event payloads should be sent.
Your server must be publicly accessible and able to handle incoming POST requests from Zoho Cliq.
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" contact: {} version: 1.0.0 servers: - url: https://cliq.zoho.com/api/v3 description: Zoho Cliq US DC tags: - name: mypins description: My Pins and Chat Folders Module paths: /pin-categories: get: summary: Retrieve chat folders operationId: getPinCategories description: "Retrieve the list of chat folders for the current user, along with the chats pinned within each folder. By default, only basic details are returned for each pinned chat, but additional fields can be included as needed.\n

\n Threshold limit: 20 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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
operation_failed	Unexpected server error.

\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" tags: - mypins parameters: - name: include_fields in: query required: false description: "Comma-separated list of additional fields to include for each pinned chat. By default, only basic details are returned for pinned chats, but you can specify additional fields as needed. Available fields include:\n

chats: Include the full chat objects for each pinned chat.
recipients_summary: Include a summary of recipients for each pinned chat.
last_message_info: Include details about the last message in each pinned chat.

\n" schema: type: string example: chats,recipients_summary,last_message_info responses: '200': description: Pin folders retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/get-pin-categories-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_failed: summary: Unexpected server error value: code: operation_failed '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 post: summary: Create a chat folder operationId: createPinCategory description: "Create a new chat folder under the My Pins section. The folder must include a title and a symbol, and may optionally include a list of chats to pin within it.\n

If chat IDs are provided, the folder will be created with those chats already pinned. Otherwise, an empty chat folder will be created.\n

\n Threshold limit: 20 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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
param_missing	A required parameter is missing from the request body.
operation_not_allowed	User does not have permission for a chat in the given chat list.
max_folders_error	Maximum number of categories reached.
operation_failed	Unexpected server error.

\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" tags: - mypins requestBody: required: true description: Provide the folder title and optionally a symbol and chat IDs to populate the folder. content: application/json: schema: $ref: '#/components/schemas/create-pin-category-request' responses: '200': description: Pin folder created successfully. content: application/json: schema: $ref: '#/components/schemas/create-pin-category-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: param_missing: summary: A required parameter is missing from the request body value: code: param_missing operation_not_allowed: summary: User does not have permission for a chat in the given chat list value: code: operation_not_allowed max_folders_error: summary: Maximum number of folders reached value: code: max_folders_error operation_failed: summary: Unexpected server error value: code: operation_failed '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.CREATE delete: summary: Remove pinned chats across chat folders operationId: removeChatsAcrossCategories description: "Remove specific pinned chats from all chat folders in one request. Provide the list of chat IDs to unpin those chats from every folder they are pinned in.

This is a bulk operation that can be used when a chat is no longer relevant and needs to be removed from multiple folders at once.\n

\n Threshold limit: 20 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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
operation_failed	Unexpected server error.

\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" tags: - mypins parameters: - name: chat_ids in: query required: true description: 'Comma-separated list of chat IDs to unpin from all folders. For each provided chat ID, the chat will be removed from every folder it is currently pinned in.
Maximum limit: 25 chat IDs per request. ' schema: type: string responses: '204': description: Chats removed from all folders successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_failed: summary: Unexpected server error value: code: operation_failed '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 /pin-categories/{CATEGORY_ID}: put: summary: Modify a chat folder operationId: updatePinCategory description: "Update the title, symbol and state of a chat folder.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
client_not_synced	The provided `last_sync_time` is stale - re-fetch categories and retry.
invalid_inputs	`title`, `symbol`, `state`, or `chat_id` was sent alongside `chat_ids`.
operation_failed	Unexpected server error or invalid inputs.

\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" tags: - mypins parameters: - name: CATEGORY_ID in: path required: true description: 'Unique ID of the chat folder to update. You can obtain this ID from the Retrieve Chat Folders API, where category_id represents the ID of the chat folder. ' schema: type: string example: CATEGORY_ID requestBody: required: true description: Request body determines the operation. Send exactly one operation type per request. content: application/json: schema: $ref: '#/components/schemas/update-pin-category-details-request' responses: '204': description: Folder updated successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: client_not_synced: summary: last_sync_time is stale - re-fetch folders and retry value: code: client_not_synced invalid_inputs: summary: title, symbol, state, or chat_id was sent alongside chat_ids value: code: invalid_inputs operation_failed: summary: Unexpected server error or invalid inputs value: code: operation_failed '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 delete: summary: Delete a chat folder operationId: deletePinCategory description: "Delete a chat folder and optionally unpin all chats within it.\n
Note: The default folder i.e My Pins section cannot be deleted.\n

\n Threshold limit: 20 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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
operation_not_allowed	Cannot delete the default category.
operation_failed	Unexpected server error.

\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" tags: - mypins parameters: - name: CATEGORY_ID in: path required: true description: 'Unique ID of the chat folder to delete. You can obtain this ID from the Retrieve Chat Folders API, where category_id represents the ID of the chat folder. ' schema: type: string example: CATEGORY_ID - name: unpin_all in: query required: false description: "Determines whether to unpin all chats within the folder instead of moving them to the default folder i.e My Pins section.\n
Allowed values:
\n

true: Unpin all chats within the folder instead of moving them to the default folder.
false (default): Move chats pinned within the deleted folder to the default folder.

\n" schema: type: boolean default: false responses: '204': description: Pin folder deleted successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_not_allowed: summary: Cannot delete the default folder value: code: operation_not_allowed operation_failed: summary: Unexpected server error value: code: operation_failed '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 /pin-categories/{CATEGORY_ID1}: put: summary: Reorder a chat within a chat folder operationId: reorderChatInCategory x-display-path: /pin-categories/{CATEGORY_ID} x-virtual-endpoint: true x-note: 'CATEGORY_ID1 is a documentation aliases for CATEGORY_ID path parameter used in updatePinCategory operation. This is to display the reorderChatInCategory operation in the documentation under the same endpoint as updatePinCategory since both operations require the same path parameter and it would be more intuitive to have them under the same endpoint. The actual endpoint for reorderChatInCategory operation will still be /pin-categories/{CATEGORY_ID} as specified in the paths object. ' description: "Reorder a pinned chat within a chat folder. This allows users to prioritise certain chats within a folder by moving them up or down the list.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
client_not_synced	The provided `last_sync_time` is stale - re-fetch categories and retry.
invalid_inputs	`title`, `symbol`, `state`, or `chat_id` was sent alongside `chat_ids`.
operation_failed	Unexpected server error or invalid inputs.

\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" tags: - mypins parameters: - name: CATEGORY_ID1 in: path required: true description: "Unique ID of the chat folder to update. You can obtain this ID from the Retrieve Chat Folders API, where category_id represents the ID of the chat folder.

\nNote: CATEGORY_ID1 is a documentation alias for CATEGORY_ID, used to separate the \"Reorder a chat within a chat folder\" operation for better readability while sharing the same /pin-categories/{CATEGORY_ID} endpoint.\n" schema: type: string example: CATEGORY_ID requestBody: required: true description: Request body determines the operation. Send exactly one operation type per request. content: application/json: schema: $ref: '#/components/schemas/reorder-chat-in-category-request' responses: '204': description: Folder updated successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: client_not_synced: summary: last_sync_time is stale - re-fetch folders and retry value: code: client_not_synced invalid_inputs: summary: title, symbol, state, or chat_id was sent alongside chat_ids value: code: invalid_inputs operation_failed: summary: Unexpected server error or invalid inputs value: code: operation_failed '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 /pin-categories/{CATEGORY_ID2}: put: summary: Reorder a chat folder operationId: reorderCategory x-display-path: /pin-categories/{CATEGORY_ID} x-virtual-endpoint: true x-note: 'CATEGORY_ID2 is a documentation aliases for CATEGORY_ID path parameter used in updatePinCategory operation. This is to display the reorderCategory operation in the documentation under the same endpoint as updatePinCategory since both operations require the same path parameter and it would be more intuitive to have them under the same endpoint. The actual endpoint for reorderCategory operation will still be /pin-categories/{CATEGORY_ID} as specified in the paths object. ' description: "Reorder a chat folder within the list of chat folders. This allows users to prioritise certain folders by moving them up or down the list.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
client_not_synced	The provided `last_sync_time` is stale - re-fetch categories and retry.
invalid_inputs	`title`, `symbol`, `state`, or `chat_id` was sent alongside `chat_ids`.
operation_failed	Unexpected server error or invalid inputs.

\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" tags: - mypins parameters: - name: CATEGORY_ID2 in: path required: true description: 'Unique ID of the chat folder to update. You can obtain this ID from the Retrieve Chat Folders API, where category_id represents the ID of the chat folder.

Note: CATEGORY_ID2 is a documentation alias for CATEGORY_ID, used to separate the "Reorder a chat folder" operation for better readability while sharing the same /pin-categories/{CATEGORY_ID} endpoint. ' schema: type: string example: CATEGORY_ID requestBody: required: true description: Request body determines the operation. Send exactly one operation type per request. content: application/json: schema: $ref: '#/components/schemas/reorder-category-request' responses: '204': description: Folder updated successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: client_not_synced: summary: last_sync_time is stale - re-fetch folders and retry value: code: client_not_synced invalid_inputs: summary: title, symbol, state, or chat_id was sent alongside chat_ids value: code: invalid_inputs operation_failed: summary: Unexpected server error or invalid inputs value: code: operation_failed '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 /pin-categories/{CATEGORY_ID3}: put: summary: Replace chats in a chat folder x-display-path: /pin-categories/{CATEGORY_ID} x-virtual-endpoint: true x-note: 'CATEGORY_ID3 is a documentation aliases for CATEGORY_ID path parameter used in updatePinCategory operation. This is to display the replaceChatInCategory operation in the documentation under the same endpoint as updatePinCategory since both operations require the same path parameter and it would be more intuitive to have them under the same endpoint. The actual endpoint for replaceChatInCategory operation will still be /pin-categories/{CATEGORY_ID} as specified in the paths object. ' operationId: bulkUpdateChatsInCategory description: "Replace the existing chats in the specified chat folder with a new set of chats. Chats not included in the request will be removed from the folder.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
client_not_synced	The provided `last_sync_time` is stale - re-fetch categories and retry.
invalid_inputs	`title`, `symbol`, `state`, or `chat_id` was sent alongside `chat_ids`.
operation_failed	Unexpected server error or invalid inputs.

\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" tags: - mypins parameters: - name: CATEGORY_ID3 in: path required: true description: "Unique ID of the chat folder to update. You can obtain this ID from the Retrieve Chat Folders API, where category_id represents the ID of the chat folder.

\nNote: CATEGORY_ID3 is a documentation alias for CATEGORY_ID, used to separate the \"Replace chats in a chat folder\" operation for better readability while sharing the same /pin-categories/{CATEGORY_ID} endpoint. \n" schema: type: string example: CATEGORY_ID requestBody: required: true description: Request body determines the operation. Send exactly one operation type per request. content: application/json: schema: $ref: '#/components/schemas/bulk-update-chats-in-category-request' responses: '204': description: Folder updated successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: client_not_synced: summary: last_sync_time is stale - re-fetch folders and retry value: code: client_not_synced invalid_inputs: summary: title, symbol, state, or chat_id was sent alongside chat_ids value: code: invalid_inputs operation_failed: summary: Unexpected server error or invalid inputs value: code: operation_failed '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 /chats/{CHAT_ID}/pins: post: summary: Pin a chat to a chat folder operationId: pinChat description: "Pin a chat for quick access either directly under the My Pins section or within a specific chat folder.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
max_pins_error	The user has reached the maximum number of pinned chats in the category.
chat_access_denied	Caller is not a participant of this chat.
operation_not_allowed	Caller does not have permission to pin this chat.
chat_operation_failed	Unexpected server error.

\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" tags: - mypins parameters: - name: CHAT_ID in: path required: true description: Unique ID of the chat to pin. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID requestBody: required: false description: Optionally provide a category_id to pin the chat under a specific folder. content: application/json: schema: $ref: '#/components/schemas/pin-chat-request' responses: '200': description: Chat pinned successfully. content: application/json: schema: $ref: '#/components/schemas/pin-chat-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: max_pins_error: summary: The user has reached the maximum number of pinned chats in the folder value: code: max_pins_error chat_access_denied: summary: Caller is not a participant of this chat value: code: chat_access_denied operation_not_allowed: summary: Caller does not have permission to pin this chat value: code: operation_not_allowed chat_operation_failed: summary: Unexpected server error value: code: chat_operation_failed '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 delete: summary: Unpin a chat operationId: unpinChat description: "Remove a pinned chat from the My Pins section and all associated chat folders. The chat will no longer appear in any pinned location.\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 Possible Error Codes\n Click to expand\n

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Error Code	Description
chat_access_denied	Caller is not a participant of this chat.
chat_operation_failed	Unexpected server error.

\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" tags: - mypins parameters: - name: CHAT_ID in: path required: true description: Unique ID of the chat to unpin. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID responses: '200': description: Chat unpinned successfully. content: application/json: schema: $ref: '#/components/schemas/unpin-chat-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: chat_access_denied: summary: Caller is not a participant of this chat value: code: chat_access_denied chat_operation_failed: summary: Unexpected server error value: code: chat_operation_failed '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 components: schemas: create-pin-category-response: type: object description: Response envelope after creating a pin folder. properties: url: type: string type: type: string example: pin_categories data: $ref: '#/components/schemas/pin-category' example: url: /v3/pin-categories type: pin_categories data: category_id: '4000000020001' state: expanded symbol: ':razz:' title: Priority Workitems create-pin-category-request: type: object description: Request body for creating a new pin folder. required: - title properties: title: type: string maxLength: 255 description: 'Display title of the chat folder.
Maximum Length: 255 characters. ' symbol: type: string maxLength: 50 description: 'Emoji or zomoji symbol for the folder.
Maximum Length: 50 characters.
Send an empty string to create the folder without a symbol. ' chat_ids: type: array maxItems: 100 description: 'Optional list of chat IDs to pin within the folder.
Maximum chat IDs: 100.
If provided, these chats will be pinned in the order specified. Otherwise, the folder will be created empty. ' items: type: string example: title: Priority Workitems symbol: ':razz:' chat_ids: - '1488288613043522033' reorder-category-request: type: object description: "Request body for updating a pin folder. Send exactly one operation type per request.

\nOperation types:\n

Reorder a Folder: Send pin_above only (no chat_id) with required last_sync_time.

\n" required: - last_sync_time properties: pin_above: type: string description: 'Unique ID of the chat folder above which the specified chat folder should be placed.
If not provided, the folder will be moved to the end of the chat folder list. ' last_sync_time: description: '

Timestamp of the client''s most recent sync state.
This is used to ensure the chat folder has not been modified since the client last synced.
If the provided timestamp is outdated, the request will be rejected to prevent conflicting updates.

Format: Accepts either ISO 8601 datetime strings or epoch timestamps. ' example: pin_above: '4000000020002' last_sync_time: '2024-01-01T12:00:00Z' bulk-update-chats-in-category-request: type: object description: "Request body for updating a pin folder. Send exactly one operation type per request.

\nOperation types:\n

Bulk Update Chats: Send chat_ids (array) with required last_sync_time.

\n" required: - chat_ids - last_sync_time properties: chat_ids: type: array maxItems: 100 description: "

Array of chat IDs that should be present in the chat folder, with a maximum of 100 chats.
The provided list completely replaces the existing chats in the folder.
To add a new chat without removing existing ones, include both the existing and new chat IDs in the request.

\nUse the Retrieve Chat Folders API to get the current list of pinned chats in a folder and then modify that list as needed and send it back in this request to update the folder's contents.

\nFor new Chat IDs, you can retrieve them from the List Chats API or List Channels API from the chat object returned in message payloads.\n" items: type: string last_sync_time: description: "

Timestamp of the client's most recent sync state.
This is used to ensure the chat folder has not been modified since the client last synced.
If the provided timestamp is outdated, the request will be rejected to prevent conflicting updates.

\nFormat: Accepts either ISO 8601 datetime strings or epoch timestamps.\n" example: chat_ids: - '1488288613043522033' - '1488288613043522034' last_sync_time: '2024-01-01T12:00:00Z' pin-category: type: object description: 'Represents a pin folder (chat folder) object. Fields marked conditional are only present when the matching include_fields value is requested.

Note: The default folder only contains category_id: "default" with no other fields. ' properties: category_id: type: string description: Unique ID of the folder, or "default" for the default folder. title: type: string description: Display title of the folder. symbol: type: string description: Emoji or zomoji symbol for the folder. state: type: string description: Whether the folder is expanded or collapsed. enum: - expanded - collapsed chats: type: array description: Conditional - only present when include_fields contains chats. items: $ref: '#/components/schemas/pinned-chat' get-pin-categories-response: type: object description: Response envelope for listing all pin folders. properties: url: type: string type: type: string example: pin_categories data: type: array items: $ref: '#/components/schemas/pin-category' example: url: /v3/pin-categories type: pin_categories data: - category_id: default - category_id: '4000000020001' state: expanded symbol: ':razz:' title: Cliq! chats: - chat_id: '1488288613043522033' chat_type: channel name: Product Launch participant_count: 12 is_pinned: true reorder-chat-in-category-request: type: object description: "Request body for updating a pin folder. Send exactly one operation type per request.

\nOperation types:\n

Reorder a Chat: Send chat_id with optional pin_above and required last_sync_time.

\n" required: - chat_id - last_sync_time properties: chat_id: type: string description: 'Unique ID of the chat to be reordered within the chat folder. ' pin_above: type: string description: 'Unique ID of the chat above which the specified chat should be placed. If not provided, the chat will be moved to the end of the chat folder. ' last_sync_time: description: '

Timestamp of the client''s most recent sync state.
This is used to ensure the chat folder has not been modified since the client last synced.
If the provided timestamp is outdated, the request will be rejected to prevent conflicting updates.

Format: Accepts either ISO 8601 datetime strings or epoch timestamps. ' example: chat_id: '1488288613043522033' pin_above: '1488288613043522034' last_sync_time: '2024-01-01T12:00:00Z' error-response: type: object description: Error response returned by the My Pins API. properties: message: type: string description: Human-readable error description. code: type: string description: Machine-readable error code. enum: - operation_failed - operation_not_allowed - param_missing - max_folders_error - client_not_synced - invalid_inputs - max_pins_error - chat_access_denied - chat_operation_failed update-pin-category-details-request: type: object description: "Request body for updating a pin folder. Send exactly one operation type per request.

\nOperation types:\n

Update Folder Details: Send title, symbol, and/or state.

\n" properties: title: type: string maxLength: 255 description: 'Update title of the chat folder.
Maximum Length: 255 characters. ' symbol: type: string maxLength: 50 description: 'Update emoji or zomoji symbol for the folder.
Maximum Length: 50 characters.
Send an empty string to remove the symbol. ' state: type: string enum: - expanded - collapsed description: "Toggle the folder's expanded or collapsed state.
\nAllowed values:
\n

expanded: The folder is expanded to show its contents.
collapsed: The folder is collapsed to hide its contents.

\n" example: title: Deliverables for Q3 symbol: ':smile:' state: collapsed pin-chat-response: type: object description: Response envelope after pinning a chat. properties: type: type: string example: chat.pin data: type: object properties: chat_id: type: string category_id: type: string example: type: chat.pin data: chat_id: '2890538000000012345' category_id: '2890538000000011111' pin-chat-request: type: object description: Request body for pinning a chat. All fields are optional. properties: category_id: type: string description: 'Unique ID of the chat folder to pin the chat under. If omitted, the chat will be pinned under My Pins section (default folder).

To learn how to retrieve this ID, see Retrieve Chat Folders API, where category_id represents the ID of the chat folder. ' example: category_id: '2890538000000011111' unpin-chat-response: type: object description: Response envelope after unpinning a chat. properties: type: type: string example: chat.unpin data: type: object properties: chat_id: type: string example: type: chat.unpin data: chat_id: '2890538000000012345' pinned-chat: type: object description: Represents a pinned chat entry within a folder. properties: chat_id: type: string description: ID of the pinned chat. chat_type: type: string description: Type of the chat, such as direct_message, bot, channel, group_chat. name: type: string description: Display name of the chat. participant_count: type: integer description: Number of participants in the chat. recipients_summary: type: array description: Conditional - requires both chats and recipients_summary in include_fields. items: type: object properties: id: type: string description: User ID of the participant. name: type: string description: Display name of the participant. last_message_info: type: object description: Conditional - requires both chats and last_message_info in include_fields. properties: id: type: string description: Message ID. sender: type: object properties: id: type: string name: type: string time: type: string description: ISO 8601 datetime of the message. type: type: string description: Message type. content: type: object properties: text: type: string is_pinned: type: boolean description: Whether the chat is currently pinned. 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/