> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Retrieve and manage CometChat conversations with REST APIs, including recent chats, last messages, unread counts, and metadata.

A **Conversation** represents an ongoing message exchange between a user and another user (1-on-1) or a group. Each conversation tracks the last message, unread count, and metadata — making it easy to build a "Recent Chats" list.

### Key behaviors

* Conversations are automatically created when the first message is exchanged.
* For groups with more than **300 members**, conversations and unread message counts are not updated.
* Conversations can have up to **25 tags**, each up to 100 characters (UTF8mb4).
* A user can pin up to **5 conversations**. Exceeding this limit returns `ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED`.
* An app can pin up to **5 conversations globally**, shown at the top for every end user. Exceeding this limit returns `ERR_SYSTEM_PINNED_CONVERSATIONS_LIMIT_EXCEEDED`.
* The `lastMessage` property is not visible if the message has been deleted or if a new group has no messages yet.

### How conversations connect to other resources

* **Users** — A 1-on-1 conversation is between two [Users](/rest-api/users). The `conversationWith` field contains the other user's details.
* **Groups** — A group conversation is tied to a [Group](/rest-api/groups). The `conversationWith` field contains the group's details.
* **Messages** — The `lastMessage` field reflects the most recent [Message](/rest-api/messages) in the conversation.

### Available operations

| Operation | Method | Endpoint | Description |
| - | - | - | - |
| [List Conversations](/rest-api/conversations/list-conversations) | `GET` | `/conversations` | Retrieve all conversations for a user |
| [Get Conversation](/rest-api/conversations/get-conversation) | `GET` | `/conversations/{conversationId}` | Retrieve a specific conversation *(deprecated)* |
| [Delete Conversation](/rest-api/conversations/delete-conversation) | `DELETE` | `/conversations/{conversationId}` | Delete a conversation for a user *(deprecated)* |
| [Get User Conversation](/rest-api/conversations/get-user-conversation) | `GET` | `/users/{uid}/conversation` | Retrieve a 1-on-1 conversation with a specific user |
| [Get Group Conversation](/rest-api/conversations/get-group-conversation) | `GET` | `/groups/{guid}/conversation` | Retrieve a group conversation |
| [Update User Conversation](/rest-api/conversations/update-user-conversation) | `PUT` | `/users/{uid}/conversation` | Update tags on a 1-on-1 conversation |
| [Update Group Conversation](/rest-api/conversations/update-group-conversation) | `PUT` | `/groups/{guid}/conversation` | Update tags on a group conversation |
| [Reset User Conversation](/rest-api/conversations/reset-user-conversation) | `DELETE` | `/users/{uid}/conversation` | Reset unread count for a 1-on-1 conversation |
| [Reset Group Conversation](/rest-api/conversations/reset-group-conversation) | `DELETE` | `/groups/{guid}/conversation` | Reset unread count for a group conversation |
| [Mark User Conversation as Read](/rest-api/conversations/mark-user-conversation-as-read) | `POST` | `/users/{uid}/conversation/read` | Mark all messages as read in a 1-on-1 conversation |
| [Mark Group Conversation as Read](/rest-api/conversations/mark-group-conversation-as-read) | `POST` | `/groups/{guid}/conversation/read` | Mark all messages as read in a group conversation |
| [Mark User Conversation as Delivered](/rest-api/conversations/mark-user-conversation-as-delivered) | `POST` | `/users/{uid}/conversation/delivered` | Mark all messages as delivered in a 1-on-1 conversation |
| [Mark Group Conversation as Delivered](/rest-api/conversations/mark-group-conversation-as-delivered) | `POST` | `/groups/{guid}/conversation/delivered` | Mark all messages as delivered in a group conversation |
| [Mark Conversation as Unread](/rest-api/conversations/mark-conversation-messages-as-unread) | `DELETE` | `/users/{uid}/conversation/read` | Mark a user conversation as unread |
| [Mark Group Conversation as Unread](/rest-api/conversations/mark-group-conversation-as-unread) | `DELETE` | `/groups/{guid}/conversation/read` | Mark a group conversation as unread |

### Conversation properties

| Property | Type | Description |
| - | - | - |
| **conversationId** | string | Unique conversation identifier. Format: `user_{uid}` for 1-on-1 or `group_{guid}` for group conversations. |
| **conversationType** | string | Type of conversation: `user` or `group`. |
| **unreadMessageCount** | integer | Number of unread messages in this conversation. |
| **lastMessage** | object | Details of the most recent message in the conversation. Not present if the message was deleted or if a new group has no messages. |
| **conversationWith** | object | Details of the other user (for 1-on-1) or the group (for group conversations). |
| **createdAt** | integer | UNIX timestamp of when the conversation was created. |
| **updatedAt** | integer | UNIX timestamp of when the conversation was last updated. |

### Error handling

| Error Code | Description |
| - | - |
| `ERR_UID_NOT_FOUND` | The specified user does not exist |
| `ERR_CONVERSATION_NOT_FOUND` | The specified conversation does not exist. This error code applies only to the deprecated [Get Conversation](/rest-api/conversations/get-conversation) and [Delete Conversation](/rest-api/conversations/delete-conversation) APIs. |
| `ERR_CONVERSATION_NOT_ACCESSIBLE` | The conversation is not accessible to the user. A user can access their own one-to-one conversations, and group conversations they are a member of. This error is also thrown when the conversation has no messages yet, as the conversation has not been created on CometChat. |

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

For all system limits (unread counts, tag counts, group thresholds, etc.), see [Properties and Constraints](/articles/properties-and-constraints).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.