> ## 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 conversations using the CometChat Flutter SDK.

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // Fetch conversations list
  ConversationsRequest request = (ConversationsRequestBuilder()
    ..limit = 30
  ).build();

  await request.fetchNext(
    onSuccess: (List<Conversation> conversations) {
      for (Conversation conv in conversations) {
        debugPrint("Conversation: ${conv.conversationId}");
      }
    },
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Get a specific conversation
  CometChat.getConversation("UID", "user",
    onSuccess: (Conversation conv) => debugPrint("Got: ${conv.conversationId}"),
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Tag a conversation
  CometChat.tagConversation("UID", "user", ["archived"],
    onSuccess: (Conversation conv) => debugPrint("Tagged: ${conv.conversationId}"),
    onError: (CometChatException e) => debugPrint("Error: ${e.message}"),
  );

  // Convert message to conversation
  Conversation conversation = CometChat.getConversationFromMessage(message);
  ```
</Accordion>

Conversations provide the last message for every one-on-one and group conversation the logged-in user is part of. Each [`Conversation`](/sdk/reference/entities#conversation) object includes the other participant (user or group), the last message, unread counts, and optional tags. Use this to build a Recent Chats list.

## Retrieve List of Conversations

<Note>
  **Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/flutter/overview)
</Note>

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

Fetching using this builder will return [`Conversation`](/sdk/reference/entities#conversation) objects.

### ConversationsRequestBuilder Parameters

The `ConversationsRequestBuilder` to fetch conversations with various filters.

| Property | Type | Description |
| - | - | - |
| `limit` | `int?` | Number of conversations to fetch per request. Default is 30, max is 50. |
| `conversationType` | `String?` | Filter by `CometChatConversationType.user` or `CometChatConversationType.group`. If not set, both types are returned. |
| `withUserAndGroupTags` | `bool?` | Include user/group tags in the response. Default is `false`. |
| `withTags` | `bool?` | Include conversation tags in the response. Default is `false`. |
| `tags` | `List<String>?` | Fetch only conversations matching the specified tags. |
| `userTags` | `List<String>?` | Fetch only user conversations where the user has the specified tags. |
| `groupTags` | `List<String>?` | Fetch only group conversations where the group has the specified tags. |
| `includeBlockedUsers` | `bool?` | Include conversations with blocked users. Default is `false`. |
| `withBlockedInfo` | `bool?` | Include blocked user information (`hasBlockedMe`, `blockedByMe`). Default is `false`. |
| `searchKeyword` | `String?` | Search conversations by user or group name. Requires Conversation & Advanced Search. |
| `unread` | `bool?` | Fetch only conversations with unread messages. Requires Conversation & Advanced Search. Default is `false`. |
| `setPage` | `int?` | Fetch conversations from a particular page. |
| `hideAgentic` | `bool?` | Exclude AI agent conversations from results. Default is `false`. |
| `onlyAgentic` | `bool?` | Fetch only AI agent conversations. Default is `false`. |

### Set Limit

Set the number of conversations to fetch per request.

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

<Note>
  The default value for `limit` is 30 and the max value is 50.
</Note>

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

When conversations are fetched successfully, the response will include an array of [`Conversation`](/sdk/reference/entities#conversation) objects filtered by the specified type.

### With User and Group Tags

Use `withUserAndGroupTags = true` to include user/group tags in the `Conversation` object. Default is `false`.

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

When conversations are fetched successfully, the response will include `tags` arrays on the `conversationWith` objects (user or group).

### Set User Tags

Fetch user conversations where the user has specific tags.

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

When conversations are fetched successfully, the response will include only user conversations where the user has the specified tags.

### Set Group Tags

Fetch group conversations where the group has specific tags.

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

When conversations are fetched successfully, the response will include only group conversations where the group has the specified tags.

### With Tags

Use `withTags = true` to include conversation tags in the response. Default is `false`.

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

### Set Tags

Fetch conversations that have specific 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

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

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

When conversations are fetched successfully, the response includes conversations with blocked users. To also get blocked info details (`blockedByMe`, `hasBlockedMe`), set `withBlockedInfo` to `true`.

### With Blocked Info

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

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

### Search Conversations

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

When conversations are fetched successfully, the response includes conversations where the user or group name matches the search keyword.

### Unread Conversations

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

When conversations are fetched successfully, the response includes only conversations with unread messages (`unreadMessageCount` > 0).

### Hide Agentic Conversations

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

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

### Only Agentic Conversations

Use `onlyAgentic = true` to fetch only AI agent conversations.

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

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

When conversations are fetched successfully, the response will include only conversations with AI agents. Agent users have `role: "@agentic"` and include agent-specific metadata.

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

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


          }, onError: (CometChatException e){

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

<Accordion title="Response">
  **On Success** — A `List<Conversation>` containing conversation objects with their associated user/group and last message details:

  <span id="fetch-conversations-conversation-object" style={{scrollMarginTop: '100px'}} />

  **Conversation Object (per item in list):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `conversationType` | string | Type of conversation | `"user"` |
  | `conversationWith` | object | User or Group the conversation is with | [See below ↓](#fetch-conversations-conversationwith-user-object) |
  | `lastMessage` | object | Last message in the conversation | [See below ↓](#fetch-conversations-lastmessage-object) |
  | `updatedAt` | number | Epoch timestamp of last update | `1745554729` |
  | `unreadMessageCount` | number | Count of unread messages | `2` |
  | `tags` | array | Tags associated with the conversation | `[]` |
  | `unreadMentionsCount` | number | Count of unread mentions | `0` |
  | `lastReadMessageId` | number | ID of the last read message | `398` |
  | `latestMessageId` | number | ID of the latest message | `401` |

  ***

  <span id="fetch-conversations-conversationwith-user-object" style={{scrollMarginTop: '100px'}} />

  **`conversationWith` Object (User):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the user | `"cometchat-uid-2"` |
  | `name` | string | Display name of the user | `"George Alan"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"offline"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745550000` |

  ***

  <span id="fetch-conversations-conversationwith-group-object" style={{scrollMarginTop: '100px'}} />

  **`conversationWith` Object (Group):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `guid` | string | Unique identifier of the group | `"cometchat-guid-1"` |
  | `name` | string | Display name of the group | `"Flutter Devs"` |
  | `icon` | string | Group icon URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"` |
  | `description` | string | Group description | `"A group for Flutter developers"` |
  | `membersCount` | number | Number of members in the group | `5` |
  | `metadata` | object | Custom metadata | `{}` |
  | `joinedAt` | number | Epoch timestamp when the user joined | `1745500000` |
  | `hasJoined` | boolean | Whether the current user has joined | `true` |
  | `createdAt` | number | Epoch timestamp when the group was created | `1745400000` |
  | `owner` | string | UID of the group owner | `"cometchat-uid-1"` |
  | `updatedAt` | number | Epoch timestamp of last update | `1745554729` |
  | `tags` | array | Group tags | `[]` |
  | `type` | string | Group type | `"public"` |
  | `scope` | string | Scope of the current user in the group | `"admin"` |
  | `password` | string | Group password (for password-protected groups) | `null` |
  | `isBannedFromGroup` | boolean | Whether the current user is banned | `false` |

  ***

  <span id="fetch-conversations-lastmessage-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage` Object (TextMessage):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `id` | number | Unique message ID | `401` |
  | `metadata` | object | Custom metadata attached to the message | `{}` |
  | `receiver` | object | Receiver user object | [See below ↓](#fetch-conversations-lastmessage-receiver-object) |
  | `editedBy` | string | UID of the user who edited the message | `null` |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `sentAt` | number | Epoch timestamp when the message was sent | `1745554729` |
  | `receiverUid` | string | UID of the receiver | `"cometchat-uid-2"` |
  | `type` | string | Type of the message | `"text"` |
  | `readAt` | number | Epoch timestamp when the message was read | `0` |
  | `deletedBy` | string | UID of the user who deleted the message | `null` |
  | `deliveredAt` | number | Epoch timestamp when the message was delivered | `1745554730` |
  | `deletedAt` | number | Epoch timestamp when the message was deleted | `0` |
  | `replyCount` | number | Number of replies to this message | `0` |
  | `sender` | object | Sender user object | [See below ↓](#fetch-conversations-lastmessage-sender-object) |
  | `receiverType` | string | Type of the receiver | `"user"` |
  | `editedAt` | number | Epoch timestamp when the message was edited | `0` |
  | `parentMessageId` | number | ID of the parent message (for threads) | `-1` |
  | `readByMeAt` | number | Epoch timestamp when read by the current user | `0` |
  | `category` | string | Message category | `"message"` |
  | `deliveredToMeAt` | number | Epoch timestamp when delivered to the current user | `1745554730` |
  | `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
  | `text` | string | The text content of the message | `"Hey, are you available for a call?"` |
  | `tags` | array | List of tags associated with the message | `[]` |
  | `unreadRepliesCount` | number | Count of unread replies | `0` |
  | `mentionedUsers` | array | List of mentioned users | `[]` |
  | `hasMentionedMe` | boolean | Whether the current user is mentioned | `false` |
  | `reactions` | array | List of reactions on the message | `[]` |
  | `moderationStatus` | string | Moderation status of the message | `null` |
  | `quotedMessageId` | number | ID of the quoted message | `null` |

  ***

  <span id="fetch-conversations-lastmessage-sender-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.sender` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the sender | `"cometchat-uid-2"` |
  | `name` | string | Display name of the sender | `"George Alan"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"offline"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745550000` |

  ***

  <span id="fetch-conversations-lastmessage-receiver-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.receiver` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the receiver | `"cometchat-uid-1"` |
  | `name` | string | Display name of the receiver | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |
</Accordion>

<Accordion title="Error">
  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` |
  | `message` | string | Human-readable error message | `"Failed to fetch the requested data."` |
  | `details` | string | Additional technical details | `"An unexpected error occurred while retrieving conversations."` |
</Accordion>

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

## Tag Conversation

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

Use `tagConversation()` to add tags to a conversation.

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

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

<Accordion title="Response">
  **On Success** — A `Conversation` object containing the updated conversation with the applied tags:

  <span id="tag-conversation-object" style={{scrollMarginTop: '100px'}} />

  **Conversation Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `conversationType` | string | Type of conversation | `"user"` |
  | `conversationWith` | object | User or Group the conversation is with | [See below ↓](#tag-conversation-conversationwith-user-object) |
  | `lastMessage` | object | Last message in the conversation | [See below ↓](#tag-conversation-lastmessage-object) |
  | `updatedAt` | number | Epoch timestamp of last update | `1745554729` |
  | `unreadMessageCount` | number | Count of unread messages | `0` |
  | `tags` | array | Tags associated with the conversation | `["archived"]` |
  | `unreadMentionsCount` | number | Count of unread mentions | `0` |
  | `lastReadMessageId` | number | ID of the last read message | `398` |
  | `latestMessageId` | number | ID of the latest message | `401` |

  ***

  <span id="tag-conversation-conversationwith-user-object" style={{scrollMarginTop: '100px'}} />

  **`conversationWith` Object (User):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the user | `"cometchat-uid-1"` |
  | `name` | string | Display name of the user | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |

  ***

  <span id="tag-conversation-lastmessage-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage` Object (TextMessage):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `id` | number | Unique message ID | `401` |
  | `metadata` | object | Custom metadata attached to the message | `{}` |
  | `receiver` | object | Receiver user object | [See below ↓](#tag-conversation-lastmessage-receiver-object) |
  | `editedBy` | string | UID of the user who edited the message | `null` |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `sentAt` | number | Epoch timestamp when the message was sent | `1745554729` |
  | `receiverUid` | string | UID of the receiver | `"cometchat-uid-1"` |
  | `type` | string | Type of the message | `"text"` |
  | `readAt` | number | Epoch timestamp when the message was read | `0` |
  | `deletedBy` | string | UID of the user who deleted the message | `null` |
  | `deliveredAt` | number | Epoch timestamp when the message was delivered | `1745554730` |
  | `deletedAt` | number | Epoch timestamp when the message was deleted | `0` |
  | `replyCount` | number | Number of replies to this message | `0` |
  | `sender` | object | Sender user object | [See below ↓](#tag-conversation-lastmessage-sender-object) |
  | `receiverType` | string | Type of the receiver | `"user"` |
  | `editedAt` | number | Epoch timestamp when the message was edited | `0` |
  | `parentMessageId` | number | ID of the parent message (for threads) | `-1` |
  | `readByMeAt` | number | Epoch timestamp when read by the current user | `0` |
  | `category` | string | Message category | `"message"` |
  | `deliveredToMeAt` | number | Epoch timestamp when delivered to the current user | `1745554730` |
  | `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
  | `text` | string | The text content of the message | `"Hey, are you available for a call?"` |
  | `tags` | array | List of tags associated with the message | `[]` |
  | `unreadRepliesCount` | number | Count of unread replies | `0` |
  | `mentionedUsers` | array | List of mentioned users | `[]` |
  | `hasMentionedMe` | boolean | Whether the current user is mentioned | `false` |
  | `reactions` | array | List of reactions on the message | `[]` |
  | `moderationStatus` | string | Moderation status of the message | `null` |
  | `quotedMessageId` | number | ID of the quoted message | `null` |

  ***

  <span id="tag-conversation-lastmessage-sender-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.sender` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the sender | `"cometchat-uid-1"` |
  | `name` | string | Display name of the sender | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |

  ***

  <span id="tag-conversation-lastmessage-receiver-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.receiver` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the receiver | `"cometchat-uid-1"` |
  | `name` | string | Display name of the receiver | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |
</Accordion>

<Accordion title="Error">
  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` |
  | `message` | string | Human-readable error message | `"Failed to tag the conversation."` |
  | `details` | string | Additional technical details | `"An unexpected error occurred while tagging the conversation."` |
</Accordion>

<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?*

Use `getConversation()` to fetch a specific conversation.

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

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

<Accordion title="Response">
  **On Success** — A `Conversation` object containing the details of the requested conversation:

  <span id="get-conversation-object" style={{scrollMarginTop: '100px'}} />

  **Conversation Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `conversationType` | string | Type of conversation | `"user"` |
  | `conversationWith` | object | User or Group the conversation is with | [See below ↓](#get-conversation-conversationwith-user-object) |
  | `lastMessage` | object | Last message in the conversation | [See below ↓](#get-conversation-lastmessage-object) |
  | `updatedAt` | number | Epoch timestamp of last update | `1745554729` |
  | `unreadMessageCount` | number | Count of unread messages | `0` |
  | `tags` | array | Tags associated with the conversation | `[]` |
  | `unreadMentionsCount` | number | Count of unread mentions | `0` |
  | `lastReadMessageId` | number | ID of the last read message | `398` |
  | `latestMessageId` | number | ID of the latest message | `401` |

  ***

  <span id="get-conversation-conversationwith-user-object" style={{scrollMarginTop: '100px'}} />

  **`conversationWith` Object (User):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the user | `"cometchat-uid-1"` |
  | `name` | string | Display name of the user | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |

  ***

  <span id="get-conversation-lastmessage-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage` Object (TextMessage):**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `id` | number | Unique message ID | `401` |
  | `metadata` | object | Custom metadata attached to the message | `{}` |
  | `receiver` | object | Receiver user object | [See below ↓](#get-conversation-lastmessage-receiver-object) |
  | `editedBy` | string | UID of the user who edited the message | `null` |
  | `conversationId` | string | Unique conversation identifier | `"cometchat-uid-1_user_cometchat-uid-2"` |
  | `sentAt` | number | Epoch timestamp when the message was sent | `1745554729` |
  | `receiverUid` | string | UID of the receiver | `"cometchat-uid-1"` |
  | `type` | string | Type of the message | `"text"` |
  | `readAt` | number | Epoch timestamp when the message was read | `0` |
  | `deletedBy` | string | UID of the user who deleted the message | `null` |
  | `deliveredAt` | number | Epoch timestamp when the message was delivered | `1745554730` |
  | `deletedAt` | number | Epoch timestamp when the message was deleted | `0` |
  | `replyCount` | number | Number of replies to this message | `0` |
  | `sender` | object | Sender user object | [See below ↓](#get-conversation-lastmessage-sender-object) |
  | `receiverType` | string | Type of the receiver | `"user"` |
  | `editedAt` | number | Epoch timestamp when the message was edited | `0` |
  | `parentMessageId` | number | ID of the parent message (for threads) | `-1` |
  | `readByMeAt` | number | Epoch timestamp when read by the current user | `0` |
  | `category` | string | Message category | `"message"` |
  | `deliveredToMeAt` | number | Epoch timestamp when delivered to the current user | `1745554730` |
  | `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
  | `text` | string | The text content of the message | `"Hey, are you available for a call?"` |
  | `tags` | array | List of tags associated with the message | `[]` |
  | `unreadRepliesCount` | number | Count of unread replies | `0` |
  | `mentionedUsers` | array | List of mentioned users | `[]` |
  | `hasMentionedMe` | boolean | Whether the current user is mentioned | `false` |
  | `reactions` | array | List of reactions on the message | `[]` |
  | `moderationStatus` | string | Moderation status of the message | `null` |
  | `quotedMessageId` | number | ID of the quoted message | `null` |

  ***

  <span id="get-conversation-lastmessage-sender-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.sender` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the sender | `"cometchat-uid-1"` |
  | `name` | string | Display name of the sender | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |

  ***

  <span id="get-conversation-lastmessage-receiver-object" style={{scrollMarginTop: '100px'}} />

  **`lastMessage.receiver` Object:**

  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `uid` | string | Unique identifier of the receiver | `"cometchat-uid-1"` |
  | `name` | string | Display name of the receiver | `"Andrew Joseph"` |
  | `link` | string | Profile link | `null` |
  | `avatar` | string | Avatar URL | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata` | object | Custom metadata | `{}` |
  | `status` | string | Online status | `"online"` |
  | `role` | string | User role | `"default"` |
  | `statusMessage` | string | Status message | `null` |
  | `tags` | array | User tags | `[]` |
  | `hasBlockedMe` | boolean | Whether this user has blocked the current user | `false` |
  | `blockedByMe` | boolean | Whether the current user has blocked this user | `false` |
  | `lastActiveAt` | number | Epoch timestamp of last activity | `1745554700` |
</Accordion>

<Accordion title="Error">
  | Parameter | Type | Description | Sample Value |
  | - | - | - | - |
  | `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` |
  | `message` | string | Human-readable error message | `"Failed to fetch the requested data."` |
  | `details` | string | Additional technical details | `"An unexpected error occurred while retrieving the conversation."` |
</Accordion>

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

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Delete Conversation" icon="trash" href="/sdk/flutter/delete-conversation">
    Remove conversations from the logged-in user's list
  </Card>

  <Card title="Typing Indicators" icon="keyboard" href="/sdk/flutter/typing-indicators">
    Show real-time typing status in conversations
  </Card>

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

  <Card title="Receive Messages" icon="inbox" href="/sdk/flutter/receive-messages">
    Listen for incoming messages in real-time
  </Card>
</CardGroup>


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