Retrieve Conversations

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

AI Integration Quick Reference

// 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)

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

Use ConversationsRequestBuilder to configure filters, then call fetchNext() to retrieve up to 50 conversations per request.

Set Limit

Set the number of conversations to fetch per request.

Java (Set Limit)

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

Kotlin (Set Limit)

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

Java

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

Kotlin

val conversationsRequest = ConversationsRequestBuilder()
  .setLimit(50)
  .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
  .build()

With User and Group Tags

Use withUserAndGroupTags(true) to include user/group tags in the response. Default is false.

Java

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

Kotlin

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

Set User Tags

Fetch user conversations where the user has specific tags.

Java

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

Kotlin

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

Set Group Tags

Fetch group conversations where the group has specific tags.

Java

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

Kotlin

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

Use withTags(true) to include conversation tags in the response. Default is false.

When withTags(true) is set, each conversation’s tags field will be populated. Access tags using getTags().

Additional Field	Getter	Return Type	Description
tags	getTags()	List<String>	Tags associated with the conversation

Java

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

Kotlin

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

Set Tags

Fetch conversations that have specific tags.

Java

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

Kotlin

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

Include Blocked Users

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

Java

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

Kotlin

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

With Blocked Info

Use withBlockedInfo(true) to include blocked user information in the response.

Java

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

Kotlin

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

Java

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

Kotlin

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

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)

Java

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

Kotlin

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

Hide Agentic Conversations

Use hideAgentic(true) to exclude AI agent conversations from the list.

Java

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

Kotlin

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

Only Agentic Conversations

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

Java

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

Kotlin

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

hideAgentic() and onlyAgentic() are mutually exclusive — use only one per request.

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.

Java

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

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

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

Kotlin

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

Use tagConversation() to add tags to a Conversation.

Parameter	Description
conversationWith	UID or GUID of the user/group
conversationType	user or group
tags	List of tags to add

Java

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

CometChat.tagConversation(id, conversationType, 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());
  }
});

Kotlin

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

Use getConversation() to fetch a specific Conversation.

Parameter	Description
conversationWith	UID or GUID of the user/group
conversationType	user or group

Java

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

Kotlin

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

  }

  @Override
  public void onError(CometChatException e) {

  }
});

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.

Java

Conversation conversation = CometChatHelper.getConversationFromMessage(message);

Kotlin

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.

Conversation Payload Structure

Conversation Object

The Conversation object returned by SDK methods contains the following fields:

Parameter	Type	Description
conversationId	String	Unique conversation identifier
conversationType	String	Type of conversation. Values: "user", "group"
conversationWith	AppEntity	The User or Group in the conversation
lastMessage	BaseMessage	Last message in the conversation
unreadMessageCount	int	Number of unread messages in the conversation
unreadMentionsCount	int	Number of unread mentions in the conversation
updatedAt	long	Unix timestamp of last conversation update
tags	Array<String>	List of tags for conversation organization
lastReadMessageId	long	ID of the last read message
latestMessageId	long	ID of the latest message

Sample Conversation Object:

{
  "conversationId": "user_123_user_456",
  "conversationType": "user",
  "conversationWith": {
    "uid": "user_456",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png",
    "status": "online",
    "role": "default",
    "lastActiveAt": 1699900000,
    "tags": ["premium", "verified"]
  },
  "lastMessage": {
    "id": 12345,
    "muid": "msg_abc123",
    "type": "text",
    "receiverType": "user",
    "category": "message",
    "sentAt": 1699900000,
    "deliveredAt": 1699900001,
    "readAt": 1699900002,
    "metadata": {"priority": "high"},
    "conversationId": "user_123_user_456"
  },
  "unreadMessageCount": 3,
  "unreadMentionsCount": 1,
  "updatedAt": 1699900000,
  "tags": ["important", "work"],
  "lastReadMessageId": 12340,
  "latestMessageId": 12345
}

User Object (conversationWith)

When conversationType is "user", the conversationWith field contains a User object:

Parameter	Type	Description
uid	String	Unique identifier of the user
name	String	Display name of the user
avatar	String	URL to user’s profile picture
link	String	URL to user’s profile page
role	String	User role for access control
metadata	JSONObject	Custom data set by developer
status	String	User online status. Values: "online", "offline"
statusMessage	String	Custom status message
lastActiveAt	long	Unix timestamp of last activity
hasBlockedMe	boolean	Whether this user has blocked the logged-in user
blockedByMe	boolean	Whether the logged-in user has blocked this user
tags	Array<String>	List of tags for user identification
deactivatedAt	long	Unix timestamp when user was deactivated (0 if active)

Group Object (conversationWith)

When conversationType is "group", the conversationWith field contains a Group object:

Parameter	Type	Description
guid	String	Unique identifier of the group
name	String	Display name of the group
type	String	Group type. Values: "public", "private", "password"
icon	String	URL to group icon
description	String	Group description
owner	String	UID of group owner
metadata	JSONObject	Custom data set by developer
membersCount	int	Number of group members
tags	Array<String>	List of tags for group identification
hasJoined	boolean	Whether logged-in user has joined
scope	String	User’s scope in group. Values: "admin", "moderator", "participant"
createdAt	long	Unix timestamp when group was created
updatedAt	long	Unix timestamp of last group update

LastMessage Object

The lastMessage field contains a BaseMessage object with key fields:

Parameter	Type	Description
id	long	Unique message identifier
muid	String	Developer-defined message ID
type	String	Message type. Values: "text", "image", "video", "audio", "file", "custom"
receiverType	String	Type of receiver. Values: "user", "group"
category	String	Message category. Values: "message", "action", "call"
sentAt	long	Unix timestamp when message was sent
deliveredAt	long	Unix timestamp when message was delivered
readAt	long	Unix timestamp when message was read
metadata	JSONObject	Custom message metadata
conversationId	String	Associated conversation identifier
sender	User	User who sent the message

---

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