> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.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>