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

Set Limit

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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.

Set Conversation Type

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

TypeScript

let limit: number = 30,
  conversationType: string = "group",
  conversationRequest: CometChat.ConversationsRequest = 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.

With User and Group Tags

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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.

JavaScript

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

TypeScript

let limit: number = 30,
  userTags: Array<String> = ["tag1"],
  conversationRequest: CometChat.ConversationsRequest = 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.

JavaScript

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

TypeScript

let limit: number = 30,
  groupTags: Array<String> = ["tag1"],
  conversationRequest: CometChat.ConversationsRequest = 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.

With Tags

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

TypeScript

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

Set Tags

Fetch conversations that have specific tags.

Set Tags

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

TypeScript

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

Include Blocked Users

Use setIncludeBlockedUsers(true) to include conversations with users you’ve blocked.

JavaScript

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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.

JavaScript

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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)

JavaScript

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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)

JavaScript

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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.

JavaScript

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

TypeScript

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

Only Agentic Conversations

Use setOnlyAgentic(true) to fetch only AI agent conversations.

JavaScript

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

TypeScript

let limit: number = 30,
  conversationRequest: CometChat.ConversationsRequest = 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

Call build() to create the request, then fetchNext() to retrieve conversations. Maximum 50 per request.

Conversations Request

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

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

The Conversation object contains:

Field	Description
conversationId	ID of the conversation
conversationType	Type of conversation (user/group)
lastMessage	Last message in the conversation
conversationWith	User or Group object
unreadMessageCount	Unread message count
unreadMentionsCount	Count of unread mentions
lastReadMessageId	ID of the last read message
latestMessageId	ID of the latest message
tags	Tags associated with the conversation (when using withTags)

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

Tag Conversation

let tags = ["archivedChat"];

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

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

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

Get Conversation

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

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

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.

Convert Message to Conversation

CometChat.CometChatHelper.getConversationFromMessage(message).then(
  (conversation) => {
    console.log("Conversation Object", conversation);
  }, (error) => {
    console.log("Error while converting message object", error);
  }
);

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

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