> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve Conversations
> Fetch recent CometChat conversations for chat lists, with support for one-on-one and group conversation filters.
Conversations provide the last messages for every one-on-one and group conversation the logged-in user is a part of. This makes it easy for you to build a **Recent Chat** list.
## Retrieve List of Conversations
*In other words, as a logged-in user, how do I retrieve the latest conversations that I've been a part of?*
To fetch the list of conversations, you can use the `ConversationsRequest` class. To use this class i.e. to create an object of the `ConversationsRequest` class, you need to use the `ConversationsRequestBuilder` class. The `ConversationsRequestBuilder` class allows you to set the parameters based on which the conversations are to be fetched.
Fetching using this builder will return [`Conversation`](/sdk/reference/entities#conversation) objects.
The `ConversationsRequestBuilder` to fetch conversations with various filters.
### Set Limit
Set the number of conversations to fetch per request.
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.build();
```
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.build();
```
### Set Conversation Type
Filter by conversation type: `user` for one-on-one or `group` for group conversations. If not set, both types are returned.
```typescript theme={null}
let limit: number = 30,
conversationType: string = "group",
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setConversationType(conversationType)
.build();
```
````javascript let limit = 30, conversationType= "group", conversationRequest= theme={null}
new CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setConversationType(conversationType) .build(); ```
The default value for `setLimit` is 30 and the max value is 50.
When conversations are fetched successfully, the response will include an array of [`Conversation`](/sdk/reference/entities#conversation) objects filtered by the specified type.
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| ---------------- | ----------------------- | ----------- | -------------------------------------------- |
| conversationType | `getConversationType()` | `string` | Type of conversation (`"user"` or `"group"`) |
### With User and Group Tags
Use `withUserAndGroupTags(true)` to include user/group tags in the response. Default is `false`.
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.withUserAndGroupTags(true)
.build();
````
````javascript let limit = 30, conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit)
.withUserAndGroupTags(true) .build(); ```
When conversations are fetched successfully, the response will include `tags` arrays on the `conversationWith` objects (user or group).
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| --------------------- | --------------------------------- | ----------- | ---------------------------------------------------------- |
| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the user or group in the conversation |
### Set User Tags
Fetch user conversations where the user has specific tags.
```typescript
let limit: number = 30,
userTags: Array = ["tag1"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setUserTags(userTags)
.build();
````
````javascript let limit = 30, userTags= ["tag1"], conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setUserTags(userTags) .build(); ```
When conversations are fetched successfully, the response will include only user conversations where the user has the specified tags.
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| --------------------- | --------------------------------- | ----------- | ------------------------------------------------- |
| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the user in the conversation |
### Set Group Tags
Fetch group conversations where the group has specific tags.
```typescript
let limit: number = 30,
groupTags: Array = ["tag1"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setGroupTags(groupTags)
.build();
````
````javascript let limit = 30, groupTags= ["tag1"], conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setGroupTags(groupTags) .build(); ```
When conversations are fetched successfully, the response will include only group conversations where the group has the specified tags.
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| --------------------- | --------------------------------- | ----------- | -------------------------------------------------- |
| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the group in the conversation |
### With Tags
Use `withTags(true)` to include conversation tags in the response. Default is `false`.
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.withTags(true)
.build();
````
````javascript let limit = 30, conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit) .withTags(true)
.build(); ```
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| ----- | ----------- | ----------- | ------------------------------------- |
| tags | `getTags()` | `string[]` | Tags associated with the conversation |
### Set Tags
Fetch conversations that have specific tags.
```typescript
let limit: number = 30,
tags: Array = ["archivedChat"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setTags(tags)
.build();
````
````javascript let limit = 30, tags= ["archivedChat"], conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit) .setTags(tags)
.build(); ```
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| ----- | ----------- | ----------- | ------------------------------------- |
| tags | `getTags()` | `string[]` | Tags associated with the conversation |
### Include Blocked Users
Use `setIncludeBlockedUsers(true)` to include conversations with users you've blocked.
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setIncludeBlockedUsers(true)
.build();
````
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setIncludeBlockedUsers(true)
.build();
```
When conversations are fetched successfully, the response includes conversations with blocked users. To also get blocked info details (`blockedByMe`, `blockedByMeAt`, `blockedAt`), set `withBlockedInfo` to `true`.
### With Blocked Info
Use `setWithBlockedInfo(true)` to include blocked user information in the response.
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setWithBlockedInfo(true)
.build();
```
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setWithBlockedInfo(true)
.build();
```
Relevant fields to access on returned conversations:
| Field | Getter | Return Type | Description |
| ------------- | ----------------------------------------- | ----------- | --------------------------------------------------- |
| blockedByMe | `getConversationWith().getBlockedByMe()` | `boolean` | Whether the logged-in user has blocked this user |
| hasBlockedMe | `getConversationWith().getHasBlockedMe()` | `boolean` | Whether this user has blocked the logged-in user |
| blockedByMeAt | `getConversationWith().blockedByMeAt` | `number` | Timestamp when the logged-in user blocked this user |
| blockedAt | `getConversationWith().blockedAt` | `number` | Timestamp when this user was blocked |
### Search Conversations
Use `setSearchKeyword()` to search conversations by user or group name.
This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setSearchKeyword("Hiking")
.build();
```
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setSearchKeyword("Hiking")
.build();
```
When conversations are fetched successfully, the response includes conversations where the user or group name matches the search keyword.
### Unread Conversations
Use `setUnread(true)` to fetch only conversations with unread messages.
This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setUnread(true)
.build();
```
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setUnread(true)
.build();
```
When conversations are fetched successfully, the response includes only conversations with unread messages (`unreadMessageCount` > 0).
### Hide Agentic Conversations
Use `setHideAgentic(true)` to exclude AI agent conversations from the list.
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setHideAgentic(true)
.build();
```
```javascript theme={null}
let limit = 30;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setHideAgentic(true)
.build();
```
### Only Agentic Conversations
Use `setOnlyAgentic(true)` to fetch only AI agent conversations.
```typescript theme={null}
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.setOnlyAgentic(true)
.build();
```
````javascript let limit = 30, conversationRequest= new theme={null}
CometChat.ConversationsRequestBuilder() .setLimit(limit) .setOnlyAgentic(true)
.build(); ```
The `setHideAgentic()` and `setOnlyAgentic()` methods are mutually exclusive. You should only use one of them in a single request builder instance.
When conversations are fetched successfully, the response will include only conversations with AI agents. Agent users have `role: "@agentic"` and include agent-specific metadata.
### Fetch Conversations
After configuring the builder, call `build()` to create the request, then `fetchNext()` to retrieve conversations. Maximum 50 per request. Call `fetchNext()` repeatedly on the same object to paginate.
```typescript
let limit: number = 30,
conversationsRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.build();
conversationsRequest.fetchNext().then(
(conversationList: CometChat.Conversation[]) => {
console.log("Conversations list received:", conversationList);
},
(error: CometChat.CometChatException) => {
console.log("Conversations list fetching failed with error:", error);
}
);
````
```javascript theme={null}
let limit = 30;
let conversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.build();
conversationsRequest.fetchNext().then(
(conversationList) => {
console.log("Conversations list received:", conversationList);
},
(error) => {
console.log("Conversations list fetching failed with error:", error);
}
);
```
The `fetchNext()` method returns an array of [`Conversation`](/sdk/reference/entities#conversation) objects.
## Tag Conversation
Use `tagConversation()` to add tags to a conversation.
| Parameter | Description |
| ------------------ | ----------------------------- |
| `conversationWith` | UID or GUID of the user/group |
| `conversationType` | `user` or `group` |
| `tags` | Array of tags to add |
```typescript theme={null}
let conversationWith: string = "UID",
tags: Array = ["archivedChat"],
conversationType: string = "user";
CometChat.tagConversation(conversationWith, conversationType, tags).then(
(conversation: CometChat.Conversation) => {
console.log("conversation", conversation);
},
(error: CometChat.CometChatException) => {
console.log("error while fetching a conversation", error);
}
);
```
```javascript theme={null}
let conversationWith = "UID",
tags = ["archivedChat"],
conversationType = "user";
CometChat.tagConversation(conversationWith, conversationType, tags).then(
(conversation) => {
console.log("conversation", conversation);
},
(error) => {
console.log("error while fetching a conversation", error);
}
);
```
The tags for conversations are one-way. This means that if user A tags a conversation with user B, that tag will be applied to that conversation only for user A.
When the conversation is tagged successfully, the response will return a single [`Conversation`](/sdk/reference/entities#conversation) object (not an array) with the `tags` field included.
The `tagConversation()` method returns a [`Conversation`](/sdk/reference/entities#conversation) object with the `tags` field populated.
Relevant fields to access on returned conversation:
| Field | Getter | Return Type | Description |
| ----- | ----------- | ----------- | -------------------------------- |
| tags | `getTags()` | `string[]` | Tags applied to the conversation |
## Retrieve Single Conversation
Use `getConversation()` to fetch a specific conversation.
| Parameter | Description |
| ------------------ | ----------------------------- |
| `conversationWith` | UID or GUID of the user/group |
| `conversationType` | `user` or `group` |
```typescript theme={null}
let conversationWith: string = "UID",
conversationType: string = "user";
CometChat.getConversation(conversationWith, conversationType).then(
(conversation: CometChat.Conversation) => {
console.log("conversation", conversation);
},
(error: CometChat.CometChatException) => {
console.log("error while fetching a conversation", error);
}
);
```
```javascript theme={null}
let conversationWith = "UID",
conversationType = "user";
CometChat.getConversation(conversationWith, conversationType).then(
(conversation) => {
console.log("conversation", conversation);
},
(error) => {
console.log("error while fetching a conversation", error);
}
);
```
When the conversation is fetched successfully, the response will return a single [`Conversation`](/sdk/reference/entities#conversation) object (not an array).
The `getConversation()` method returns a single [`Conversation`](/sdk/reference/entities#conversation) object.
## Convert Messages to Conversations
Use `CometChatHelper.getConversationFromMessage()` to convert a received message into a [`Conversation`](/sdk/reference/entities#conversation) object. Useful for updating your Recent Chats list when receiving real-time messages.
```typescript theme={null}
let message: CometChat.TextMessage | CometChat.MediaMessage | CometChat.CustomMessage;
CometChat.CometChatHelper.getConversationFromMessage(message).then(
(conversation: CometChat.Conversation) => {
console.log("Conversation Object", conversation);
},(error: CometChat.CometChatException) => {
console.log("Error while converting message object", error);
}
);
```
```javascript theme={null}
CometChat.CometChatHelper.getConversationFromMessage(message).then(
(conversation) => {
console.log("Conversation Object", conversation);
}, (error) => {
console.log("Error while converting message object", error);
}
);
```
When converting a message to a conversation, `unreadMessageCount` and `tags`
won't be available. Manage unread counts in your client-side code.
The `getConversationFromMessage()` method returns a [`Conversation`](/sdk/reference/entities#conversation) object.
***
## Next Steps
Remove conversations from the logged-in user's list
Listen for incoming messages to update conversation lists in real time
Show real-time typing status in conversations
Track message delivery and read status per conversation