> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-angular-v5-docs-update.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.
```dart theme={null}
// Fetch conversations list
ConversationsRequest request = (ConversationsRequestBuilder()
..limit = 30
).build();
await request.fetchNext(
onSuccess: (List 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);
```
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
**Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/flutter/overview)
*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?` | Fetch only conversations matching the specified tags. |
| `userTags` | `List?` | Fetch only user conversations where the user has the specified tags. |
| `groupTags` | `List?` | 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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
).build();
```
The default value for `limit` is 30 and the max value is 50.
### Set Conversation Type
Filter by conversation type: `user` for one-on-one or `group` for group conversations. If not set, both types are returned.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..conversationType = CometChatConversationType.user
).build();
```
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`.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..withUserAndGroupTags = true
).build();
```
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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..userTags = ["tag1"]
).build();
```
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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..groupTags = ["tag1"]
).build();
```
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`.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..withTags = true
).build();
```
### Set Tags
Fetch conversations that have specific tags.
```dart theme={null}
List tags = [];
tags.add("archived");
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..tags = tags
).build();
```
### Include Blocked Users
Use `includeBlockedUsers = true` to include conversations with users you've blocked.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..includeBlockedUsers = true
).build();
```
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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..withBlockedInfo = true
).build();
```
### Search Conversations
Use `searchKeyword` to search conversations by user or group name.
This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](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)
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..searchKeyword = "Hiking"
).build();
```
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.
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)
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..unread = true
).build();
```
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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..hideAgentic = true
).build();
```
### Only Agentic Conversations
Use `onlyAgentic = true` to fetch only AI agent conversations.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
..onlyAgentic = true
).build();
```
`hideAgentic` and `onlyAgentic` are mutually exclusive — use only one per request.
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.
```dart theme={null}
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
..limit = 50
).build();
conversationRequest.fetchNext(
onSuccess: (List conversations){
}, onError: (CometChatException e){
});
```
**On Success** — A `List` containing conversation objects with their associated user/group and last message details:
**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` |
***
**`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` |
***
**`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` |
***
**`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` |
***
**`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` |
***
**`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` |
| 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."` |
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 |
```dart theme={null}
String conversationWith = "cometchat-uid-1"; //id of the user/group
String conversationType = "user";
List 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}");
}
);
```
**On Success** — A `Conversation` object containing the updated conversation with the applied tags:
**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` |
***
**`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` |
***
**`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` |
***
**`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` |
***
**`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` |
| 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."` |
The tags for conversations are one-way. This means that if user A tags a conversation with user B, that tag will be applied to that conversation only for user A.
## Retrieve Single Conversation
*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` |
```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}");
}
);
```
**On Success** — A `Conversation` object containing the details of the requested conversation:
**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` |
***
**`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` |
***
**`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` |
***
**`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` |
***
**`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` |
| 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."` |
## 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.
```dart theme={null}
Conversation conversation = CometChat.getConversationFromMessage(message);
```
While converting a `Message` object to a `Conversation` object, the `unreadMessageCount` & `tags` will not be available in the `Conversation` object. The unread message count needs to be managed in your client-side code.
***
## Next Steps
Remove conversations from the logged-in user's list
Show real-time typing status in conversations
Track message delivery and read status
Listen for incoming messages in real-time