> ## 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 CometChat conversations in Flutter apps using conversation request builders.

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
    ).build();
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..conversationType = CometChatConversationType.user
    ).build();
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..withUserAndGroupTags  = true
    ).build();
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..withTags = true
    ).build();
    ```
  </Tab>
</Tabs>

### Set Tags

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> tags = [];
    tags.add("archived");
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..tags = tags
    ).build();
    ```
  </Tab>
</Tabs>

### Include Blocked Users

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..includeBlockedUsers = true
    ).build();
    ```
  </Tab>
</Tabs>

### With Blocked Info

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..withBlockedInfo = true
    ).build();
    ```
  </Tab>
</Tabs>

### Search Conversations

This method helps you search a conversation based on 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="Dart">
    ```dart theme={null}
      ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
        ..limit = 50
        ..searchKeyword = "Hiking"
      ).build();
    ```
  </Tab>
</Tabs>

### Unread Conversations

This method helps you fetch unread conversations.

<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="Dart">
    ```dart theme={null}
      ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
        ..limit = 50
        ..unread = true
      ).build();
    ```
  </Tab>
</Tabs>

### Filter by User Tags

This method helps you filter conversations based on specific user tags.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> userTags = ["premium", "verified"];
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..userTags = userTags
    ).build();
    ```
  </Tab>
</Tabs>

### Filter by Group Tags

This method helps you filter conversations based on specific group tags.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    List<String> groupTags = ["support", "sales"];
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..groupTags = groupTags
    ).build();
    ```
  </Tab>
</Tabs>

### Hide Agentic Conversations

This method helps you hide AI-driven (agentic) conversations from the list. Agentic conversations are those involving AI agents.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..hideAgentic = true
    ).build();
    ```
  </Tab>
</Tabs>

### Only Agentic Conversations

This method helps you fetch only AI-driven (agentic) conversations. This is useful when you want to display a separate list of AI agent conversations.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
      ..limit = 50
      ..onlyAgentic = true
    ).build();
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
        ..limit = 50
      ).build();

    conversationRequest.fetchNext(
          onSuccess: (List<Conversation> conversations){


          }, onError: (CometChatException e){

          }
    ```
  </Tab>
</Tabs>

The `Conversation`object consists of the below 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                            |
| `unreadMentionsCount` | the count of unread mentions in the conversation.                    |
| `lastReadMessageId`   | the ID of the last read message in the conversation (int type).      |

## Tag Conversation

*In other words, as a logged-in user, how do I tag a conversation?*

In order to tag a specific conversation, you can use the `tagConversation()` method. The `tagConversation()` method accepts three parameters.

1. `conversationWith`: UID/GUID of the user/group whose conversation you want to fetch.

2. `conversationType`: The `conversationType` variable can hold one of the below two values:

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

3. `tags`: The `tags` variable will be a list of tags you want to add to a conversation.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String conversationWith = "cometchat-uid-1"; //id of the user/group
    String conversationType = "user";
    List<String> tags = [];
    tags.add("archived");

    CometChat.tagConversation(conversationWith, conversationType, tags,
    	onSuccess: (Conversation conversation) {
    		debugPrint("Conversation tagged Successfully : $conversation");
    	}, onError: (CometChatException e) {
    		debugPrint("Conversation tagging failed  : ${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

*In other words, as a logged-in user, how do I retrieve a specific conversation?*

In order to fetch a specific conversation, you can use the `getConversation` method. The `getConversation` method accepts two parameters.

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

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String conversationWith = "cometchat-uid-1"; //id of the user/group
    String conversationType = "user";
    CometChat.getConversation(conversationWith, conversationType,
    	onSuccess: (Conversation conversation) {
    		debugPrint("Fetch Conversation Successfully : $conversation");
    	}, onError: (CometChatException e) {
    		debugPrint("Fetch Conversation  failed  : ${e.message}");
    	}
    );
    ```
  </Tab>
</Tabs>

## Convert Messages to Conversations

As per our [Receive Messages](/sdk/flutter/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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Conversation conversation = CometChat.getConversationFromMessage(message);
    ```
  </Tab>
</Tabs>

<Info>
  While converting `Message` object to `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.
</Info>