Skip to content

docs(rest-api): add pin, save & interacted endpoints (ENG-38785) #488

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pranavkamble-cometchat wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(rest-api): add pin, save & interacted endpoints (ENG-38785) #488

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf910b3
docs(rest-api): add pin, save & interacted endpoints (ENG-38785)
pranavkamble-cometchat Sep 2, 2026
2fc48a1
docs(rest-api): rename pinned-conversation pages to "global pinned" (…
pranavkamble-cometchat Sep 2, 2026
f6986b1
docs(rest-api): re-sync specs from fixed OAS, drop calls.json (ENG-38…
pranavkamble-cometchat Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions articles/error-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@
| Error Code | Error Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auth Errors** | |
| `AUTH_ERR_EMPTY_APPID` | Indicates empty appId in the headers. |

Check warning on line 10 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L10 

Did you really mean 'appId'?
| `AUTH_ERR_INVALID_APPID` | Indicates invalid appId or it does not exist in a region. |

Check warning on line 11 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L11 

Did you really mean 'appId'?
| `AUTH_ERR_EMPTY_APIKEY` | Indicates empty API Key in the headers. |
| `AUTH_ERR_APIKEY_NOT_FOUND` | Indicates incorrect API Key in the headers. |
| `AUTH_ERR_NO_ACCESS` | Indicates API Key in the headers can not be used to perform the action. For example, the API key with authOnly scope cannot be used to create a user. |

Check warning on line 14 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L14 

Did you really mean 'authOnly'?
| `AUTH_ERR_EMPTY_AUTH_HEADER` | Indicates the Basic Auth header is missing. Applies to Management APIs, which use HTTP Basic Auth instead of the `apikey` header. |
| `AUTH_ERR_EMPTY_AUTH_TOKEN` | Indicates empty auth token in the headers. |
| `AUTH_ERR_AUTH_TOKEN_NOT_FOUND` | Indicates incorrect auth token. |
| **API Key Errors** | |
| `ERR_APIKEY_NOT_FOUND` | Indicates that the api key does not exists. |

Check warning on line 19 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L19 

Did you really mean 'api'?
| `ERR_APIKEY_NO_SELF_ACTION` | Indicates that the API key in the headers is same as the API key in the path param and it is performing action on it self. The API Key should not update/delete itself. |

Check warning on line 20 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L20 

Did you really mean 'param'?
| **Auth Token Errors** | |
| `ERR_AUTH_TOKEN_NOT_FOUND` | Indicates that the auth token does not exists. |
| `ERR_AUTH_TOKEN_DELETE_FAILED` | Indicates that the API failed to delete the auth token. |
Expand All @@ -40,7 +40,7 @@
| `ERR_BOT_ALREADY_EXISTS` | Indicates that a bot is already associated with the UID. |
| **Group Errors** | |
| `ERR_GUID_NOT_FOUND` | Indicates that the GUID does not exist. |
| `ERR_EMPTY_GROUP_PASS` | Indicates one from the below: 1. Empty password for password type group to create group API. 2. Empty password for pasword type group to join group API. |

Check warning on line 43 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L43 

Did you really mean 'pasword'?
| `ERR_GROUP_DELETE_FAILED` | Indicates that the API failed to delete the group. |
| `ERR_NOT_A_MEMBER` | Indicates that the user is not a member of the group. |
| `ERR_WRONG_GROUP_PASS` | Indicates password mismatch for the password type group. |
Expand All @@ -51,11 +51,11 @@
| `ERR_NO_VACANCY` | Indicates that the group is full. |
| `ERR_SAME_SCOPE` | Indicates that the existing and new scope are same. |
| `ERR_MEMBER_SCOPE_CHANGE_FAILED` | Indicates that the has failed to change the scope. |
| `ERR_NOT_A_BANNED_USER` | Indicates that the API is trying to unban non-banned user. |

Check warning on line 54 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L54 

Did you really mean 'unban'?
| `ERR_BANNED_GROUPMEMBER` | Indicates that the banned user is trying to access the group features. |
| `ERR_ALREADY_BANNED` | Indicates that the API is trying to ban an already banned user. |
| `ERR_MEMBER_BAN_FAILED` | Indicates that the API has failed to ban a user from the group. |
| `ERR_MEMBER_UNBAN_FAILED` | Indicates that the API has failed to unban a user for the group. |

Check warning on line 58 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L58 

Did you really mean 'unban'?
| `ERR_GROUP_NO_CLEARANCE` | Indicates that the user does not have permission to perform the action in the group. For example, user with participant scope can not kick users with admin or moderator scope. |
| `ERR_GROUP_NO_ADMIN_SCOPE` | Indicates that the user does not have admin scope in the group. |
| `ERR_GROUP_NO_MODERATOR_SCOPE` | Indicates that the user does not have moderator scope in the group. |
Expand All @@ -81,11 +81,16 @@
| `ERR_MESSAGE_ACTION_NOT_ALLOWED` | Indicates that the message can not be edited or deleted. For example, Action messages cannot be edited or deleted by the API. |
| `ERR_EMPTY_CUSTOM_DATA` | Indicates `data.customData` can not be empty for custom message. |
| `ERR_INVALID_MEDIA_MESSAGE` | Indicates invalid media message. |
| `ERR_INVALID_CUSTOM_DATA` | Indicates invalid data.customData. The customData should be valid JSON. |

Check warning on line 84 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L84 

Did you really mean 'customData'?
| `ERR_INVALID_METADATA` | Indicates invalid data.metadata. The metadata should be valid JSON. |
| `ERR_WRONG_MESSAGE_THREAD` | Indicates conversation mismatch for parent and a new threaded message. |
| `ERR_MESSAGE_THREAD_NESTING` | Indicates nested message threading. |
| `ERR_WRONG_MESSAGE_THREAD_CATEGORY` | Indicates conversation mismatch for parent and a new threaded message. |
| `ERR_PINNED_MESSAGES_LIMIT_EXCEEDED` | Indicates that the conversation has reached the maximum number of pinned messages allowed. |
| `ERR_SAVED_MESSAGES_LIMIT_EXCEEDED` | Indicates that the user has reached the maximum number of saved messages allowed. |
| `ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED` | Indicates that the user has reached the maximum number of pinned conversations allowed. |
| `ERR_SYSTEM_PINNED_CONVERSATIONS_LIMIT_EXCEEDED` | Indicates that the app has reached the maximum number of global pinned conversations allowed. |
| `ERR_SYSTEM_PINNED_CONVERSATION` | Indicates that the conversation is pinned for all users by the app and cannot be pinned or unpinned by a user. |
| **Calling Errors** | |
| `ERR_CALLING_SELF` | Indicates user is initiating call with himself. |
| `ERR_CALL_BUSY_SELF` | Indicates initiator of the call is participant of another ongoing call. |
Expand All @@ -101,7 +106,7 @@
| `ERR_CALL_GROUP_INVALID_STATUS` | Indicates invalid call status for a group call. For example, group call cannot have a busy status. |
| `ERR_CALL_ONGOING_TO_INVALID` | Indicates updating invalid status for an ongoing call. For example, ongoing call can not become a busy call. |
| `ERR_CALL_NOT_A_PART` | Indicates that the user is not part of the call. For example, a third user tries to join a one-to-one call. |
| `ERR_CALL_EMPTY_JOINED_AT` | Indicates that the `joinedAt` body param is required to join a group. |

Check warning on line 109 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L109 

Did you really mean 'param'?
| `ERR_CALL_NOT_STARTED` | Indicates that status of call cannot be changed from initiated to ended directly. |
| **Friends Errors** | |
| `ERR_ALREADY_FRIEND` | Indicates that the users are already friends. |
Expand All @@ -111,7 +116,7 @@
| **Block Users Errors** | |
| `ERR_CANNOT_BLOCK_SELF` | Indicates that user cannot block himself. |
| `ERR_BLOCKED_RECEIVER` | Indicates user has blocked the receiver of the message/call. |
| `ERR_BLOCKED_SENDER` | Indicates that the iniator of the call is blocked by the recipient. |

Check warning on line 119 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L119 

Did you really mean 'iniator'?
| **Extension Errors** | |
| `ERR_EXTENSION_NOT_FOUND` | Indicates extension does not exist. |
| `ERR_BLOCKED_BY_EXTENSION` | Indicates that the message is blocked by the extension. For example, human moderation extension can block the message sending. |
Expand All @@ -135,7 +140,7 @@
| `ERR_WS_ROLE_CREATION_FAILED` | Indicates role creation failure at Web Socket Server. |
| `ERR_WS_ROLE_DELETION_FAILED` | Indicates role deletion failure at Web Socket Server. |
| `ERR_WS_USER_CREATION_FAILED` | Indicates user creation failure at Web Socket Server. |
| `ERR_WS_USER_UPDATION_FAILED` | Indicates user updation failure at Web Socket Server. |

Check warning on line 143 in articles/error-guide.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

articles/error-guide.mdx#L143 

Did you really mean 'updation'?
| `ERR_WS_GROUP_CREATION_FAILED` | Indicates group creation failure at Web Socket Server. |
| `ERR_WS_GROUP_DELETION_FAILED` | Indicates group deletion failure at Web Socket Server. |
| `ERR_WS_GROUP_JOIN_FAILED` | Indicates group member join failure at Web Socket Server. |
2,571 changes: 2,017 additions & 554 deletions chat-apis.json
View file
Open in desktop

Large diffs are not rendered by default.

28 changes: 23 additions & 5 deletions data-import-apis.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2928,6 +2928,14 @@
},
"conversationWith": {
"type": "object"
},
"pinnedBy": {
"description": "UID of the user who pinned the conversation, or app_system for a global pin. Left out of the response when the conversation is not pinned.",
"type": "string"
},
"pinnedAt": {
"description": "When the conversation was pinned, in seconds. Left out of the response when the conversation is not pinned.",
"type": "integer"
}
},
"type": "object"
Expand Down Expand Up @@ -3013,6 +3021,7 @@
"type": "object"
},
"customCategorySchema": {
"title": "Custom",
"properties": {
"receiver": {
"description": "The receiver of the message.",
Expand Down Expand Up @@ -3040,11 +3049,7 @@
},
"quotedMessageId": {
"description": "ID of the message being quoted.\nIf provided, the send message response will include a `quotedMessage` node\nin the response containing the referenced message object.",
"type": "string",
"default": "message",
"enum": [
"message"
]
"type": "string"
},
"type": {
"description": "Type of the message.",
Expand Down Expand Up @@ -4040,6 +4045,7 @@
"type": "object"
},
"messageCategorySchema": {
"title": "Message",
"properties": {
"receiver": {
"description": "The receiver of the message.",
Expand Down Expand Up @@ -4427,6 +4433,18 @@
},
"updatedAt": {
"type": "integer"
},
"pinnedBy": {
"description": "UID of the user who pinned the message, or app_system when the app pinned it. Left out of the response when the message is not pinned.",
"type": "string"
},
"pinnedAt": {
"description": "When the message was pinned, in seconds. Left out of the response when the message is not pinned.",
"type": "integer"
},
"savedAt": {
"description": "When the message was saved, in seconds. Only present for the user who saved it, and left out of the response when they have not saved it.",
"type": "integer"
}
},
"type": "object"
Expand Down
13 changes: 12 additions & 1 deletion docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5048,6 +5048,11 @@
"rest-api/messages/get-message",
"rest-api/messages/update-message",
"rest-api/messages/delete-message",
"rest-api/messages/pin-message",
"rest-api/messages/unpin-message",
"rest-api/messages/save-message",
"rest-api/messages/unsave-message",
"rest-api/messages/mark-message-as-interacted",
"rest-api/messages/list-all-reactions",
"rest-api/messages/list-reactions-with-a-specific-emoji-unicode",
"rest-api/messages/add-reaction",
Expand All @@ -5069,18 +5074,24 @@
"rest-api/conversations/list-conversations",
"rest-api/conversations/get-conversation",
"rest-api/conversations/delete-conversation",
"rest-api/conversations/list-global-pinned-conversations",
"rest-api/conversations/replace-global-pinned-conversations",
"rest-api/conversations/get-user-conversation",
"rest-api/conversations/update-user-conversation",
"rest-api/conversations/reset-user-conversation",
"rest-api/conversations/mark-user-conversation-as-delivered",
"rest-api/conversations/mark-user-conversation-as-read",
"rest-api/conversations/mark-conversation-messages-as-unread",
"rest-api/conversations/pin-user-conversation",
"rest-api/conversations/unpin-user-conversation",
"rest-api/conversations/get-group-conversation",
"rest-api/conversations/update-group-conversation",
"rest-api/conversations/reset-group-conversation",
"rest-api/conversations/mark-group-conversation-as-delivered",
"rest-api/conversations/mark-group-conversation-as-read",
"rest-api/conversations/mark-group-conversation-as-unread"
"rest-api/conversations/mark-group-conversation-as-unread",
"rest-api/conversations/pin-group-conversation",
"rest-api/conversations/unpin-group-conversation"
]
}
]
Expand Down
6 changes: 6 additions & 0 deletions rest-api/conversations/list-global-pinned-conversations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: get /conversations/pinned
description: "List the CometChat global pinned conversations with REST API - the conversations pinned at the top for every end user, in display order."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/conversations/pin-group-conversation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: post /groups/{guid}/conversation/pin
description: "Pin a CometChat group conversation for a user with REST API so it appears at the top of their conversation list."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/conversations/pin-user-conversation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: post /users/{uid}/conversation/pin
description: "Pin a CometChat one-on-one conversation for a user with REST API so it appears at the top of their conversation list."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/conversations/replace-global-pinned-conversations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: put /conversations/pinned
description: "Replace the full CometChat global pinned conversation list with REST API - the conversations pinned at the top for every end user."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/conversations/unpin-group-conversation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: delete /groups/{guid}/conversation/pin
description: "Unpin a CometChat group conversation for a user with REST API, removing that user's own pin."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/conversations/unpin-user-conversation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: delete /users/{uid}/conversation/pin
description: "Unpin a CometChat one-on-one conversation for a user with REST API, removing that user's own pin."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/messages/mark-message-as-interacted.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: patch /messages/{id}/interacted
description: "Mark a CometChat message as interacted with REST API on behalf of a user."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/messages/pin-message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: post /messages/{id}/pin
description: "Pin a CometChat message in a one-on-one or group conversation with REST API, as the app or on behalf of a user."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/messages/save-message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: post /messages/{id}/save
description: "Save a CometChat message to a user's private saved list with REST API on behalf of that user."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/messages/unpin-message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: delete /messages/{id}/pin
description: "Unpin a pinned CometChat message with REST API. Any user with unpin permission can unpin, not only the user who pinned it."
---

For the complete error reference, see [Error Guide](/articles/error-guide).
6 changes: 6 additions & 0 deletions rest-api/messages/unsave-message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
openapi: delete /messages/{id}/save
description: "Remove a CometChat message from a user's saved list with REST API on behalf of that user."
---

For the complete error reference, see [Error Guide](/articles/error-guide).