Retrieve Conversations

Fetch, filter, tag, and search conversations using the CometChat JavaScript SDK.

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
const conversation = 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

Use ConversationsRequestBuilder to fetch conversations with various filters.

Set Limit

Set the number of conversations to fetch per request.

TypeScript

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

JavaScript

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

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

JavaScript

let limit = 30;
let conversationType = "group";
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setConversationType(conversationType)
  .build();

Default limit is 30, maximum is 50.

When conversations are fetched successfully, the response includes an array of Conversation objects filtered by the specified type.

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;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .withUserAndGroupTags(true)
  .build();

When conversations are fetched successfully, the response includes tags arrays on the conversationWith objects.

Set User Tags

Fetch user conversations where the user has specific tags.

TypeScript

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

JavaScript

let limit = 30;
let userTags = ["tag1"];
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setUserTags(userTags)
  .build();   

When conversations are fetched successfully, the response includes only user conversations where the user has the specified tags.

Set Group Tags

Fetch group conversations where the group has specific tags.

TypeScript

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

JavaScript

let limit = 30;
let groupTags = ["tag1"];
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setGroupTags(groupTags)
  .build();

When conversations are fetched successfully, the response includes only group conversations where the group has the specified tags.

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;
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .withTags(true)
  .build();

Set Tags

Fetch conversations that have specific tags.

TypeScript

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

JavaScript

let limit = 30;
let tags = ["archivedChat"];
let conversationRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(limit)
  .setTags(tags)
  .build();

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

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

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

JavaScript

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

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

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

JavaScript

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

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

JavaScript

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

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

JavaScript

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

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

JavaScript

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

setHideAgentic() and setOnlyAgentic() are mutually exclusive — use only one per request.

When conversations are fetched successfully, the response includes only AI agent conversations. Agent users have role: "@agentic".

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

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. Access the response data using getter methods:

Field	Getter	Return Type	Description
conversationId	getConversationId()	string	Unique conversation ID
conversationType	getConversationType()	string	Type of conversation ("user" or "group")
lastMessage	getLastMessage()	BaseMessage	The last message in the conversation
conversationWith	getConversationWith()	User | Group	The user or group this conversation is with
unreadMessageCount	getUnreadMessageCount()	number	Number of unread messages
unreadMentionsCount	getUnreadMentionsCount()	number	Count of unread mentions
lastReadMessageId	getLastReadMessageId()	string	ID of the last read message
latestMessageId	getLatestMessageId()	string	ID of the latest message
tags	getTags()	string[]	Tags associated with the conversation (when using withTags)

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

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

JavaScript

let tags = ["archivedChat"];

let conversationWith = "UID";
let conversationType = "user";

CometChat.tagConversation(conversationWith, conversationType, tags).then(
  (conversation) => {
    console.log("conversation", conversation);
  },
  (error) => {
    console.log("error while fetching a conversation", error);
  }
);

Conversation tags are one-way. If user A tags a conversation with user B, that tag only applies for user A.

When the conversation is tagged successfully, the response returns a Conversation object with the tags field.

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

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

let conversationWith = "UID";
let 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 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

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

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.

---

Next Steps

Delete Conversation

Remove conversations from the logged-in user’s list

Typing Indicators

Show real-time typing status in conversations