openapi: 3.0.0 info: title: Pin Messages description: | The Pin Messages API allows teams to highlight and manage important messages within a chat, ensuring that critical information remains visible to all participants and is not lost in the flow of conversation.

The latest version, v3, is designed to give developers precise control over what gets highlighted from meeting links and deadlines to key announcements, helping every participant stay aligned without the need to scroll through chat history.

Key Capabilities
With the v3 version of the Pin Messages API, you can: contact: {} version: 3.0.0 externalDocs: description: Find out more about Zoho Cliq APIs V3 url: https://www.zoho.com/cliq/help/restapi/v2/ servers: - url: https://cliq.zoho.com/api/v3 description: Zoho Cliq US DC tags: - name: pinmessages description: Pin Messages Module paths: /chats/{CHAT_ID}/pin-messages: get: summary: Get pinned messages operationId: getPinnedMessages description: | Returns the list of pinned messages in a chat, sorted by pin time with the most recent first. Optionally, you can fetch only the primary pinned message or use pagination for efficient retrieval.

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

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

! Possible Error Codes Click to expand
Error Code Description
operation_not_allowed User might not be a participant of that chat.
operation_failed Unexpected error while fetching the primary pin.
Error Response Format

When an error occurs, the API returns a JSON response in this format:

{"message": "A human-readable description of the error.", "code": "error_code"}

where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.

tags: - pinmessages parameters: - name: CHAT_ID in: path required: true description: Unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID - name: primary in: query required: false description: Pass this parameter (no value needed) to fetch the primary pinned message instead of the full list. schema: type: boolean - name: limit in: query required: false description: | Maximum number of pinned messages to return.
Defaults to 20 if not specified. schema: type: integer - name: next_token in: query required: false description: | Token from a previous response to fetch the next page of results. Omit to fetch the first page. schema: type: string - name: sync_token in: query required: false description: | Synchronization token for incremental sync of pinned messages.
Pass the sync_token received in an earlier response to fetch only updates after that sync point.
Format: base64 token.
Maximum length: 100 characters. schema: type: string maxLength: 100 responses: '200': description: Successful response. Returns the list of pinned messages (or the primary pinned message when primary=true). content: application/json: schema: $ref: '#/components/schemas/get-pinned-messages-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_not_allowed: summary: User is not a participant of the chat value: message: Uh-Oh! You are not authorized to do this operation. code: operation_not_allowed operation_failed: summary: Unexpected error while fetching the primary pin 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: Add a pinned message operationId: addPinnedMessage description: | Pins a message in a chat.

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

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

! Possible Error Codes Click to expand
Error Code Description
operation_failed Invalid expiry time - the specified time is in the past.
operation_not_allowed User might not be a participant of that chat.
Error Response Format

When an error occurs, the API returns a JSON response in this format:

{"message": "A human-readable description of the error.", "code": "error_code"}

where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.

tags: - pinmessages parameters: - name: CHAT_ID in: path required: true description: Unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID requestBody: required: true description: Provide the message ID, expiry time, and notification preference to pin a message. content: application/json: schema: $ref: '#/components/schemas/add-pinned-message-request' responses: '200': description: Message pinned successfully. content: application/json: schema: $ref: '#/components/schemas/add-pinned-message-response' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_failed: summary: Invalid expiry time value: message: Incorrect values submitted. code: operation_failed operation_not_allowed: summary: User is not a participant of the chat value: message: Uh-Oh! You are not authorized to do this operation. code: operation_not_allowed '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 put: summary: Reorder pinned messages operationId: reorderPinnedMessages description: | Changes the position of a pinned message in the list. If the message is reordered above the current primary pin, it automatically becomes the new primary.

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

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

! Possible Error Codes Click to expand
Error Code Description
client_not_synced The provided sync timestamp is stale. Re-fetch pins and retry.
operation_failed Incorrect values submitted.
operation_not_allowed Caller is not authorized to perform this operation.
Error Response Format

When an error occurs, the API returns a JSON response in this format:

{"message": "A human-readable description of the error.", "code": "error_code"}

where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.

tags: - pinmessages parameters: - name: CHAT_ID in: path required: true description: Unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID requestBody: required: true description: Provide the message ID to move and optionally the message above which to position it. content: application/json: schema: $ref: '#/components/schemas/reorder-pinned-message-request' responses: '204': description: Pinned message reordered 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 pins and retry value: code: client_not_synced operation_failed: summary: Incorrect values submitted value: message: Incorrect values submitted. code: operation_failed operation_not_allowed: summary: Caller is not authorized to perform this operation value: message: Uh-Oh! You are not authorized to do this operation. code: operation_not_allowed '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 pinned messages operationId: deletePinnedMessages description: | Removes one or more pinned messages from a chat.

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

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

! Possible Error Codes Click to expand
Error Code Description
operation_not_allowed Caller is not authorized to perform this operation.
Error Response Format

When an error occurs, the API returns a JSON response in this format:

{"message": "A human-readable description of the error.", "code": "error_code"}

where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.

tags: - pinmessages parameters: - name: CHAT_ID in: path required: true description: Unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID requestBody: required: false description: Supply message_ids to remove specific pinned messages. If omitted, all pinned messages in the chat are removed. content: application/json: schema: $ref: '#/components/schemas/delete-pinned-messages-request' responses: '204': description: Pinned message(s) deleted successfully. No response body. '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_not_allowed: summary: Caller is not authorized to perform this operation value: message: Uh-Oh! You are not authorized to do this operation. code: operation_not_allowed '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 /chats/{CHAT_ID}/pin-messages?primary=true: get: summary: Get primary pinned message operationId: getPrimaryPinnedMessage description: | Fetches the primary pinned message in a chat. The primary pin is the most prominently displayed pinned message, typically shown at the top of the pinned list and highlighted in the UI.

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

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

! Possible Error Codes Click to expand
Error Code Description
operation_not_allowed User might not be a participant of that chat.
operation_failed Unexpected error while fetching the primary pin.
Error Response Format

When an error occurs, the API returns a JSON response in this format:

{"message": "A human-readable description of the error.", "code": "error_code"}

where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.

tags: - pinmessages parameters: - name: CHAT_ID in: path required: true description: | Unique identifier of the chat. To learn how to retrieve this ID, see CHAT_ID in the Glossary page. schema: type: string example: CHAT_ID - name: primary in: query required: true description: | Pass this parameter without a value to retrieve only the primary pinned message of the chat, instead of the full list of pinned messages. schema: type: boolean allowEmptyValue: true example: true responses: '200': description: Successfully retrieved the primary pinned message. content: application/json: schema: $ref: '#/components/schemas/get-primary-pinned-message-response' example: type: text id: '1746000123456789001' time: '2026-04-30T09:00:00Z' sender: id: '1234567890' name: Alice Johnson content: text: Please review the Q2 report before Friday. is_pinned: true pin_information: expiry_time: -1 creator: id: '9876543210' name: Bob Smith created_time: '2026-04-30T09:15:00Z' last_modified_time: '2026-04-30T09:15:00Z' is_primary: true '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/error-response' examples: operation_not_allowed: summary: Caller is not authorized to perform this operation value: message: Uh-Oh! You are not authorized to do this operation. code: operation_not_allowed '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 components: schemas: NoResponse: type: object description: Represents an empty successful response where no payload is returned. properties: Response Code: type: string description: HTTP response code indicating no content is returned. example: 204 No response GenericResponse: type: object description: Generic successful response envelope. properties: url: type: string description: Endpoint URL associated with the response. type: type: string description: Resource type returned by the API. data: type: object description: Resource payload. additionalProperties: true additionalProperties: true pin-information: type: object description: Metadata about the pin itself. properties: expiry_time: description: | When the pin expires. -1 means no expiry. ISO 8601 datetime string when an expiry is set. oneOf: - type: integer example: -1 - type: string example: '2026-04-19T19:09:44+05:30' creator: type: object properties: name: type: string id: type: string created_time: type: string format: date-time last_modified_time: type: string format: date-time is_primary: type: boolean description: true if this is the primary (top) pinned message. pinned-message: type: object description: A pinned message object. Contains the original message fields (id, type, content, sender, time, mentions) along with pin-specific fields. properties: id: type: string type: type: string example: text content: type: object properties: text: type: string sender: type: object properties: name: type: string id: type: string time: type: string format: date-time mentions: type: array description: Present only when the message contains mentions. items: type: object properties: name: type: string id: type: string type: type: string is_pinned: type: boolean description: Always true for pinned messages. pin_information: $ref: '#/components/schemas/pin-information' get-pinned-messages-response: type: object description: Response envelope for listing all pinned messages. properties: url: type: string type: type: string example: pinmessages sync_token: type: string description: Pass in subsequent requests to fetch only pins updated since the last sync. data: type: array items: $ref: '#/components/schemas/pinned-message' example: url: /company/16557244/v3/chats/1488288613043522033/pin-messages type: pinmessages sync_token: NTB8MTc3MzkyNzUxMjcwNnw0MDAwMDAwMDExMDAz data: - is_pinned: true pin_information: expiry_time: -1 creator: name: Tim Harrison id: '16557777' created_time: '2026-03-19T19:08:32+05:30' last_modified_time: '2026-03-19T19:08:32+05:30' is_primary: true sender: name: Tim Harrison id: '16557777' type: text content: text: '{@16557498}' time: '2026-03-19T10:02:52+05:30' id: 1.7738947728961294e+23 mentions: - name: '@sharan 203' id: '16557498' type: user get-primary-pinned-message-response: type: object description: Response envelope when fetching the primary pinned message. properties: url: type: string type: type: string example: pinmessages data: $ref: '#/components/schemas/pinned-message' example: url: /company/16557244/v3/chats/1488288613043522033/pin-messages type: pinmessages data: type: text id: '1746000123456789001' time: '2026-04-30T09:00:00Z' sender: id: '1234567890' name: Alice Johnson content: text: Please review the Q2 report before Friday. is_pinned: true pin_information: expiry_time: -1 creator: id: '9876543210' name: Bob Smith created_time: '2026-04-30T09:15:00Z' last_modified_time: '2026-04-30T09:15:00Z' is_primary: true add-pinned-message-request: type: object description: Request body for pinning a message in a chat. required: - message_id - expiry_time - notify properties: message_id: type: string description: | ID of the message to pin. This message must already exist in the chat and cannot be deleted. expiry_time: description: | When the pin should expire. Accepts ISO 8601 datetime strings (e.g., "2026-04-19T19:09:44+05:30") or epoch timestamps (e.g., 1745068184000). Use -1 for no expiry. oneOf: - type: string - type: integer notify: type: boolean description: | Set to true to send a notification to chat participants about the new pin. Defaults to false. primary: type: boolean description: | Set to true to pin as the primary (top) message. Defaults to false. If this is the first pin in the chat, it automatically becomes primary regardless of this value. example: message_id: '1773894772896_12958180473' expiry_time: '2026-04-19T19:09:44+05:30' notify: false add-pinned-message-response: type: object description: Response envelope after pinning a message. properties: url: type: string type: type: string example: pinmessages data: $ref: '#/components/schemas/pinned-message' example: url: /v3/chats/1488288613043522033/pin-messages type: pinmessages data: pin_information: expiry_time: '2026-04-19T19:09:44+05:30' creator: name: Tim Harrison id: '16557777' created_time: '2026-03-19T19:08:32+05:30' last_modified_time: '2026-03-19T19:08:32+05:30' is_primary: false is_pinned: true sender: name: Tim Harrison id: '16557777' type: text content: text: Please review the deployment checklist before the release. time: '2026-03-19T10:02:52+05:30' id: '1773894772896_12958180473' reorder-pinned-message-request: type: object description: Request body for reordering a pinned message in the list. required: - message_id - last_sync_time properties: message_id: type: string description: ID of the pinned message to move. pin_above: type: string description: ID of the message above which to position. If omitted, the message is moved to the last position. last_sync_time: description: | Required for reorder operation. Accepts ISO 8601 datetime strings (e.g., "2026-04-19T19:09:44+05:30") or epoch timestamps (e.g., 1745068184000). The server rejects the request if this is stale. oneOf: - type: string - type: integer example: message_id: '1773894772896_12958180473' pin_above: '1773895219462_47318365091' last_sync_time: 1745068184000 delete-pinned-messages-request: type: object description: Request body for deleting specific pinned messages. required: - message_ids properties: message_ids: type: array description: | List of message IDs to unpin. These messages must currently be pinned in the chat. If this field is omitted or an empty array is provided, all pinned messages in the chat are removed.
Maximum 25 message IDs can be provided in a single request. minItems: 1 maxItems: 25 items: type: string example: message_ids: - '17719462_4731836509' - '17737286_1295818047' - '17732346_9876543210' error-response: type: object description: Error response returned by the Pin Messages API. properties: message: type: string description: Human-readable error description. code: type: string description: Machine-readable error code. enum: - operation_not_allowed - operation_failed - client_not_synced - pinned_message_limit_reached securitySchemes: Cliq_Auth: type: oauth2 x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f flows: implicit: authorizationUrl: https://accounts.zoho.com/oauth/v2/auth scopes: ZohoCliq.Chats.CREATE: Create Chats ZohoCliq.Chats.READ: Read Chats ZohoCliq.Chats.UPDATE: Modify Chats ZohoCliq.Chats.DELETE: Delete Chats