Retrieve Conversations - CometChat Docs

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 objects. The ConversationsRequestBuilder to fetch conversations with various filters.

Set Limit

Set the number of conversations to fetch per request.

TypeScript
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .build();

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.

let limit: number = 30,
  conversationType: string = "group",
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .setConversationType(conversationType)
    .build();

let limit = 30, conversationType= "group", conversationRequest=

new CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setConversationType(conversationType) .build(); ```
</Tab>

</Tabs>

<Note>The default value for `setLimit` is 30 and the max value is 50.</Note>

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`.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .withUserAndGroupTags(true)
  .build();

let limit = 30, conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit)
.withUserAndGroupTags(true) .build(); ```
</Tab>

</Tabs>

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.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
userTags: Array<String> = ["tag1"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setUserTags(userTags)
  .build();  

let limit = 30, userTags= ["tag1"], conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setUserTags(userTags) .build(); ```
</Tab>

</Tabs>

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.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
groupTags: Array<String> = ["tag1"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setGroupTags(groupTags)
  .build();

let limit = 30, groupTags= ["tag1"], conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit)
.setGroupTags(groupTags) .build(); ```
</Tab>

</Tabs>

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`.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
.setLimit(limit)
.withTags(true)
.build();   

let limit = 30, conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit) .withTags(true)
.build(); ```
</Tab>

</Tabs>

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.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
tags: Array<String> = ["archivedChat"],
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setTags(tags)
  .build();

let limit = 30, tags= ["archivedChat"], conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit) .setTags(tags)
.build(); ```
</Tab>

</Tabs>

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.

<Tabs>
<Tab title="TypeScript">
```typescript
let limit: number = 30,
conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setIncludeBlockedUsers(true)
  .build();  

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
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setWithBlockedInfo(true)
  .build();     

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. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

TypeScript
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .setSearchKeyword("Hiking")
    .build();  

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.

TypeScript
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .setUnread(true)
    .build();  

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
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .setHideAgentic(true)
    .build();  

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
JavaScript
JavaScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = new CometChat.ConversationsRequestBuilder()
    .setLimit(limit)
    .setOnlyAgentic(true)
    .build();  

let limit = 30, conversationRequest= new

CometChat.ConversationsRequestBuilder() .setLimit(limit) .setOnlyAgentic(true)
.build(); ```
</Tab>

</Tabs>

<Note>

The `setHideAgentic()` and `setOnlyAgentic()` methods are mutually exclusive. You should only use one of them in a single request builder instance.

</Note>

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.

<Tabs>
<Tab title="TypeScript">
```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);
}
);

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 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
JavaScript

let conversationWith: string = "UID",
  tags: Array<String> = ["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);
}
);

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 object (not an array) with the tags field included. The tagConversation() method returns a 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
JavaScript

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);
}
);

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 object (not an array). The getConversation() method returns a single Conversation object.

Convert Messages to Conversations

Use CometChatHelper.getConversationFromMessage() to convert a received message into a Conversation object. Useful for updating your Recent Chats list when receiving real-time messages.

TypeScript
JavaScript

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);
}
);

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 object.

Next Steps

Delete Conversation

Remove conversations from the logged-in user’s list

Receive Messages

Listen for incoming messages to update conversation lists in real time

Typing Indicators

Show real-time typing status in conversations

Delivery & Read Receipts

Track message delivery and read status per conversation

​Retrieve List of Conversations

​Set Limit

​Set Conversation Type

​With Blocked Info

​Search Conversations

​Unread Conversations

​Hide Agentic Conversations

​Only Agentic Conversations

​Tag Conversation

​Retrieve Single Conversation

​Convert Messages to Conversations

​Next Steps

Delete Conversation

Receive Messages

Typing Indicators

Delivery & Read Receipts

Retrieve List of Conversations

Set Limit

Set Conversation Type

With Blocked Info

Search Conversations

Unread Conversations

Hide Agentic Conversations

Only Agentic Conversations

Tag Conversation

Retrieve Single Conversation

Convert Messages to Conversations

Next Steps