Retrieve Conversations - CometChat Docs

Quick Reference for AI Agents & Developers

// Build a conversations request
let conversationsRequest = new CometChat.ConversationsRequestBuilder()
  .setLimit(30)
  .build();

// Fetch conversations (paginated)
conversationsRequest.fetchNext().then(
  conversationList => console.log("Conversations:", conversationList),
  error => console.log("Error:", error)
);

// Retrieve a single conversation
CometChat.getConversation("UID_OR_GUID", "user_or_group").then(
  conversation => console.log("Conversation:", conversation),
  error => console.log("Error:", error)
);

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.

Available via: SDK | REST API | UI Kits

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. The ConversationsRequestBuilder class allows you to set the below parameters:

Set Limit

This method sets the limit i.e. the number of conversations that should be fetched in a single iteration.

JavaScript
TypeScript

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

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

Set Conversation Type

This method can be used to fetch user or group conversations specifically. The conversationType variable can hold one of the below two values:

user - Only fetches user conversation.
group - Only fetches group conversations.

If none is set, the list of conversations will include both user and group conversations.

JavaScript
TypeScript

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

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

With User and Group Tags

This method can be used to fetch the user/group tags in the Conversation Object. By default the value is false.

JavaScript
TypeScript

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

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

Set User Tags

This method fetches user conversations that have the specified tags.

JavaScript
TypeScript

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

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

Set Group Tags

This method fetches group conversations that have the specified tags.

JavaScript
TypeScript

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

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

With Tags

This method makes sure that the tags associated with the conversations are returned along with the other details of the conversations. The default value for this parameter is false.

JavaScript
TypeScript

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

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

Set Tags

This method helps you fetch the conversations based on the specified tags.

JavaScript
TypeScript

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

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

Include Blocked Users

This method helps you fetch the conversations of users whom the logged-in user has blocked.

JavaScript
TypeScript

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

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

With Blocked Info

This method can be used to fetch the blocked information of the blocked user in the ConversationWith object.

JavaScript
TypeScript

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

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

Search Conversations

This method helps you search for a conversation based on a 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
TypeScript

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

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

Unread Conversations

This method helps you fetch unread conversations.

JavaScript
TypeScript

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

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

Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the ConversationsRequest class. Once you have the object of the ConversationsRequest class, you need to call the fetchNext() method. Calling this method will return a list of Conversation objects containing X number of users depending on the limit set. A Maximum of only 50 Conversations can be fetched at once.

JavaScript
TypeScript

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

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 consists of the following fields:

Field	Information
conversationId	ID of the conversation.
conversationType	Type of conversation. (user/group)
lastMessage	Last message in the conversation.
conversationWith	User or Group object containing the details of the user or group.
unreadMessageCount	Unread message count for the conversation.

Tag Conversation

In other words, as a logged-in user, how do I tag a conversation? To tag a specific conversation, you can use the tagConversation() method. The tagConversation() method accepts three parameters.

conversationWith: UID/GUID of the user/group whose conversation you want to tag.
conversationType: The conversationType variable can hold one of the below two values:
1. user - Only fetches user conversation.
2. group - Only fetches group conversations.
tags: The tags variable will be a list of tags you want to add to a conversation.

JavaScript

let tags = ["archivedChat"];
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.

Retrieve Single Conversation

In other words, as a logged-in user, how do I retrieve a specific conversation? To fetch a specific conversation, you can use the getConversation method. The getConversation method accepts two parameters.

conversationWith: UID/GUID of the user/group whose conversation you want to fetch.
conversationType: The conversationType variable can hold one of the below two values:

user - Only fetches user conversation.
group - Only fetches group conversations.

JavaScript

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

Convert Messages to Conversations

As per our receive messages guide, for real-time messages, you will always receive Message objects and not Conversation objects. Thus, you will need a mechanism to convert the Message object to a Conversation object. You can use the getConversationFromMessage(BaseMessage message) method of the CometChatHelper class.

JavaScript

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

While converting the Message object to the Conversation object, the unreadMessageCount & tags will not be available in the Conversation object. The unread message count needs to be managed in your client-side code.

Best Practices & Troubleshooting

Use pagination for large conversation lists

Always use fetchNext() in a loop or on-scroll handler to paginate through conversations. Fetching all conversations at once is not supported — the maximum per request is 50. Store the ConversationsRequest object and call fetchNext() repeatedly until it returns an empty list.

Keep conversation lists updated in real time

Use real-time message listeners to receive new messages, then call CometChatHelper.getConversationFromMessage() to convert incoming messages into Conversation objects and update your list. Note that unreadMessageCount and tags are not available when converting from a message — manage those on the client side.

Filter conversations effectively with tags

Use setTags() to categorize conversations (e.g., archivedChat, pinned). Remember that conversation tags are one-way — tagging a conversation only applies for the logged-in user, not the other participant.

Conversations list is empty or missing expected results

Ensure the logged-in user has actually exchanged messages with the expected users or groups. Conversations only appear once at least one message has been sent. Also verify that any filters (conversation type, tags, unread) are not excluding the results you expect.

Search or unread filter not working

The setSearchKeyword() and setUnread() methods require the Conversation & Advanced Search feature, which is only available on Advanced and Custom plans. Enable it from the CometChat Dashboard under Chats → Settings → General Configuration.

Next Steps

Delete Conversation

Remove a conversation from the logged-in user’s conversation list.

Receive Messages

Listen for real-time messages and update your conversation list.

Typing Indicators

Show real-time typing status within conversations.

Delivery & Read Receipts

Track when messages are delivered and read.

​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

​Tag Conversation

​Retrieve Single Conversation

​Convert Messages to Conversations

​Best Practices & Troubleshooting

​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

Tag Conversation

Retrieve Single Conversation

Convert Messages to Conversations

Best Practices & Troubleshooting

Next Steps