> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Conversations

> Fetch, filter, tag, and search user or group conversations using the CometChat Android SDK.

<Accordion title="AI Integration Quick Reference">
  ```kotlin theme={null}
  // 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)
  ```
</Accordion>

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.

<Tabs>
  <Tab title="Java (Set Limit)">
    ```java theme={null}
    ConversationsRequest conversationRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(100)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin (Set Limit)">
    ```kotlin theme={null}
    val conversationRequest = ConversationsRequestBuilder()
      .setLimit(100)
      .build()
    ```
  </Tab>
</Tabs>

### Set Conversation Type

Filter by conversation type: `user` for one-on-one or `group` for group conversations. If not set, both types are returned.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
      .build()
    ```
  </Tab>
</Tabs>

### With User and Group Tags

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .withUserAndGroupTags(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .withUserAndGroupTags(true)
      .build()
    ```
  </Tab>
</Tabs>

### Set User Tags

Fetch user conversations where the user has specific tags.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    List<String> tags = new ArrayList<>();
    tags.add("tag_1");
    conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(10)
      .setUserTags(tags)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val tags: MutableList<String> = ArrayList()
    tags.add("tag_1")
    conversationsRequest = ConversationsRequestBuilder()
      .setLimit(10)
      .setUserTags(tags)
      .build()
    ```
  </Tab>
</Tabs>

### Set Group Tags

Fetch group conversations where the group has specific tags.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    List<String> tags = new ArrayList<>();
    tags.add("tag_1");
    conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(10)
      .setGroupTags(tags)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val tags: MutableList<String> = ArrayList()
    tags.add("tag_1")
    conversationsRequest = ConversationsRequestBuilder()
      .setLimit(10)
      .setGroupTags(tags)
      .build()
    ```
  </Tab>
</Tabs>

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 |

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .withTags(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .withTags(true)
      .build()
    ```
  </Tab>
</Tabs>

### Set Tags

Fetch conversations that have specific tags.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    List<String> tags = new ArrayList<>();
    tags.add("archived");
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .setTags(tags)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val tags: MutableList<String> = ArrayList()
    tags.add("archived")
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .setTags(tags)
      .build()
    ```
  </Tab>
</Tabs>

### Include Blocked Users

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .includeBlockedUsers(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .includeBlockedUsers(true)
      .build()
    ```
  </Tab>
</Tabs>

### With Blocked Info

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .withBlockedInfo(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .withBlockedInfo(true)
      .build()
    ```
  </Tab>
</Tabs>

### Search Conversations

Use `setSearchKeyword()` to search conversations by user or group name.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .setSearchKeyword("Hiking")
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .setSearchKeyword("Hiking")
      .build() 
    ```
  </Tab>
</Tabs>

### Unread Conversations

Use `setUnread(true)` to fetch only conversations with unread messages.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .setUnread(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .setUnread(true)
      .build() 
    ```
  </Tab>
</Tabs>

### Hide Agentic Conversations

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .hideAgentic(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .hideAgentic(true)
      .build()
    ```
  </Tab>
</Tabs>

### Only Agentic Conversations

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
      .setLimit(50)
      .onlyAgentic(true)
      .build();
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversationsRequest = ConversationsRequestBuilder()
      .setLimit(50)
      .onlyAgentic(true)
      .build()
    ```
  </Tab>
</Tabs>

<Note>
  `hideAgentic()` and `onlyAgentic()` are mutually exclusive — use only one per request.
</Note>

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    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
      }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    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
      }
    })
    ```
  </Tab>
</Tabs>

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`](/sdk/reference/entities#user) or [`Group`](/sdk/reference/entities#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`](/sdk/reference/entities#conversation).

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    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());
      }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    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)
        }
      }
    )
    ```
  </Tab>
</Tabs>

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

## Retrieve Single Conversation

Use `getConversation()` to fetch a specific [`Conversation`](/sdk/reference/entities#conversation).

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

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    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
      }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    CometChat.getConversation(conversationWith, conversationType, new CometChat.CallbackListener<Conversation>() {
      @Override
      public void onSuccess(Conversation conversation) {

      }

      @Override
      public void onError(CometChatException e) {

      }
    });
    ```
  </Tab>
</Tabs>

## Convert Messages to Conversations

Use `CometChatHelper.getConversationFromMessage()` to convert a received message into a [`Conversation`](/sdk/reference/entities#conversation) object. Useful for updating your Recent Chats list when receiving real-time messages.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    Conversation conversation = CometChatHelper.getConversationFromMessage(message);
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val conversation = CometChatHelper.getConversationFromMessage(message)
    ```
  </Tab>
</Tabs>

<Note>
  While converting a [`Message`](/sdk/reference/messages#basemessage) object to a [`Conversation`](/sdk/reference/entities#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.
</Note>

## Conversation Payload Structure

<Accordion title="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](#user-object-conversation) or [Group](#group-object-conversation) in the conversation |
  | `lastMessage` | [BaseMessage](/sdk/reference/messages#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:**

  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

<Accordion title="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) |
</Accordion>

<Accordion title="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 |
</Accordion>

<Accordion title="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 |
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Delete Conversation" icon="trash" href="/sdk/android/delete-conversation">
    Remove conversations from the list
  </Card>

  <Card title="Typing Indicators" icon="keyboard" href="/sdk/android/typing-indicators">
    Show when users are typing
  </Card>

  <Card title="Read Receipts" icon="check-double" href="/sdk/android/delivery-read-receipts">
    Track message delivery and read status
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/android/send-message">
    Start sending messages in conversations
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.