Retrieve Conversations - CometChat Docs

AI Integration Quick Reference

// Fetch conversations list
const request = new CometChat.ConversationsRequestBuilder()
  .setLimit(30).build();
const conversations = await request.fetchNext();

// Get a specific conversation
const conversation = await CometChat.getConversation("UID", "user");

// Tag a conversation
await CometChat.tagConversation("UID", "user", ["archived"]);

// Convert message to conversation
let message = {}; // obtained from MessageListener or fetchPrevious/fetchNext
const conv = await CometChat.CometChatHelper.getConversationFromMessage(message);

Conversations provide the last message for every one-on-one and group conversation the logged-in user is part of. Each Conversation object includes the other participant (user or group), the last message, unread counts, and optional tags. Use this to build a Recent Chats 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.

TypeScript
JavaScript

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

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

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

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
JavaScript

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

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
JavaScript

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

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
JavaScript

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

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
JavaScript

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

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
JavaScript

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

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

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
JavaScript

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 User and Group Tags

​Set User Tags

​Set Group Tags

​With Tags

​Set Tags

​Include Blocked Users

​With Blocked Info

​Search Conversations

​Unread Conversations

​Hide Agentic Conversations

​Only Agentic Conversations

​Fetch 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 User and Group Tags

Set User Tags

Set Group Tags

With Tags

Set Tags

Include Blocked Users

With Blocked Info

Search Conversations

Unread Conversations

Hide Agentic Conversations

Only Agentic Conversations

Fetch Conversations

Tag Conversation

Retrieve Single Conversation

Convert Messages to Conversations

Next Steps