Retrieve Conversations - CometChat Docs

Quick Reference for AI Agents & Developers

// Fetch conversations with filters
val conversationsRequest = ConversationsRequestBuilder()
    .setLimit(50)
    .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
    .build()

conversationsRequest.fetchNext(object : CallbackListener<List<Conversation>>() {
    override fun onSuccess(conversations: List<Conversation>) { }
    override fun onError(e: CometChatException) { }
})

// Get specific conversation
CometChat.getConversation("UID_or_GUID", "user", callback)

Available via: SDK | REST API | UI Kits

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

How do I retrieve the latest conversations that I’ve been a part of? To fetch the list of conversations, use the ConversationsRequest class. 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 fetched. The ConversationsRequestBuilder class allows you to set the following parameters:

Set Limit

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

Java (Set Limit)
Kotlin (Set Limit)

ConversationsRequest conversationRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(100)
  .build();

val conversationRequest = ConversationsRequestBuilder()
  .setLimit(100)
  .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.

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
  .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.

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .withUserAndGroupTags(true)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .withUserAndGroupTags(true)
  .build()

Set User Tags

This method fetches user conversations that have the specified tags.

Java
Kotlin

List<String> tags = new ArrayList<>();
tags.add("tag_1");
conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(10)
  .setUserTags(tags)
  .build();

val tags: MutableList<String> = ArrayList()
tags.add("tag_1")
conversationsRequest = ConversationsRequestBuilder()
  .setLimit(10)
  .setUserTags(tags)
  .build()

Set Group Tags

Java
Kotlin

List<String> tags = new ArrayList<>();
tags.add("tag_1");
conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(10)
  .setGroupTags(tags)
  .build();

val tags: MutableList<String> = ArrayList()
tags.add("tag_1")
conversationsRequest = ConversationsRequestBuilder()
  .setLimit(10)
  .setGroupTags(tags)
  .build()

This method fetches group conversations that have the specified tags.

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

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .withTags(true)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .withTags(true)
  .build()

Set Tags

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

Java
Kotlin

List<String> tags = new ArrayList<>();
tags.add("archived");
ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .setTags(tags)
  .build();

val tags: MutableList<String> = ArrayList()
tags.add("archived")
val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .setTags(tags)
  .build()

Include Blocked Users

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

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .includeBlockedUsers(true)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .includeBlockedUsers(true)
  .build()

With Blocked Info

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

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .withBlockedInfo(true)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .withBlockedInfo(true)
  .build()

Search Conversations

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

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .setSearchKeyword("Hiking")
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .setSearchKeyword("Hiking")
  .build() 

Unread Conversations

This method helps you fetch unread conversations.

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setLimit(50)
  .setUnread(true)
  .build();

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .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 conversations depending on the limit set. A Maximum of only 50 Conversations can be fetched at once.

Java
Kotlin

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder().setLimit(50).build();

conversationsRequest.fetchNext(new CometChat.CallbackListener<List<Conversation>>() {
  @Override
  public void onSuccess(List<Conversation> conversations) {
    // Hanlde list of conversations

  }

  @Override
  public void onError(CometChatException e) {
    // Hanlde failure
  }
});

var conversationRequest: ConversationsRequest? = null
val LIMIT:Int=30

conversationRequest = ConversationsRequest.ConversationsRequestBuilder().setLimit(LIMIT).build()
conversationRequest?.fetchNext(object : CometChat.CallbackListener<List<Conversation>>() {
  override fun onSuccess(p0: List<Conversation>?) {
    //Handle List of Conversations
  }

  override fun onError(p0: CometChatException?) {
    //Handle Failure
  }
})

The Conversation object consists of the following fields:

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

Tag Conversation

How do I tag a conversation? To tag a specific conversation, use the tagConversation() method. The tagConversation() method accepts three 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:
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.

Java
Kotlin

String id = "cometchat-uid-1"; //id of the user/group
String conversationType = "user";
List<String> tags = new ArrayList<>();
tags.add("archived");

CometChat.tagConversation(id, conversationWith, tags, new CometChat.CallbackListener<Conversation>() {
  @Override
  public void onSuccess(Conversation conversation) {
    Log.d(TAG, conversation.toString());
  }

  @Override
  public void onError(CometChatException e) {
    Log.d(TAG, e.getMessage());
  }
});

val id = "cometchat-uid-1" //id of the user/group

val conversationType = "user"
val tags: MutableList<String> = ArrayList()
tags.add("archived")

CometChat.tagConversation(id, conversationWith, tags, object : CallbackListener<Conversation>() {
    override fun onSuccess(conversation: Conversation) {
        Log.d(TAG, conversation.toString())
    }

    override fun onError(e: CometChatException) {
        Log.d(TAG, e.message)
    }
  }
)

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

How do I retrieve a specific conversation? To fetch a specific conversation, 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.

Java
Kotlin

CometChat.getConversation(conversationWith, conversationType, new CometChat.CallbackListener<Conversation>() {
  @Override
  public void onSuccess(Conversation conversation) {
    // Handle getConversation success
  }

  @Override
  public void onError(CometChatException e) {
    // Handle getConversation error
  }
});

CometChat.getConversation(conversationWith, conversationType, new CometChat.CallbackListener<Conversation>() {
  @Override
  public void onSuccess(Conversation conversation) {

  }

  @Override
  public void onError(CometChatException e) {

  }
});

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 method for this purpose.

Java
Kotlin

Conversation conversation = CometChatHelper.getConversationFromMessage(message);

val conversation = CometChatHelper.getConversationFromMessage(message)

While converting a Message object to a 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

Use Pagination for Performance

Set a reasonable limit (30-50) and fetch conversations in batches. Maximum limit is 50 conversations per request.

Filter by Conversation Type

Use setConversationType() to fetch only user or group conversations when building separate tabs or views.

Implement Search for Large Lists

Enable “Conversation & Advanced Search” in Dashboard and use setSearchKeyword() for better user experience with many conversations.

Use Tags for Organization

Tag conversations (e.g., “archived”, “pinned”, “important”) to organize and filter conversations based on user preferences.

Handle Unread Count Client-Side

When converting messages to conversations, manage unread counts in your app since they’re not included in the conversion.

Troubleshooting

Empty Conversations List

Symptom: fetchNext() returns an empty list even though conversations exist.Cause: User hasn’t sent or received any messages, or filters are too restrictive.Solution: Remove filters temporarily to verify conversations exist. Check if the user has participated in any chats.

Search Not Working

Symptom: setSearchKeyword() doesn’t filter conversations.Cause: “Conversation & Advanced Search” feature not enabled in Dashboard.Solution: Enable the feature in CometChat Dashboard under Chats → Settings → General Configuration. Available in Advanced & Custom plans only.

Unread Filter Not Working

Symptom: setUnread(true) doesn’t filter unread conversations.Cause: “Conversation & Advanced Search” feature not enabled.Solution: Enable the feature in Dashboard. This is a premium feature available in Advanced & Custom plans.

Next Steps

Delete Conversation

Remove conversations from the list

Typing Indicators

Show when users are typing

Read Receipts

Track message delivery and read status

Send Messages

Start sending messages in conversations

​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

Typing Indicators

Read Receipts

Send Messages

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