> ## 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.
# Mentions
> Send messages with user mentions, retrieve mentioned users, and filter messages by mention metadata using the CometChat Flutter SDK.
| Field | Value |
| --------------- | --------------------------------------------------------------------------------- |
| Key Classes | `TextMessage`, `BaseMessage`, `User`, `MessagesRequest`, `MessagesRequestBuilder` |
| Key Properties | `mentionedUsers`, `hasMentionedMe` |
| Builder Methods | `mentionsWithTagInfo()`, `mentionsWithBlockedInfo()` |
| Mention Format | `<@uid:UID>` |
| Prerequisites | SDK initialized, user logged in |
```dart theme={null}
// Send a message with a mention (use <@uid:UID> format)
TextMessage textMessage = TextMessage(
text: "Hello <@uid:cometchat-uid-1>",
receiverUid: "UID",
receiverType: CometChatReceiverType.user,
type: CometChatMessageType.text,
);
CometChat.sendMessage(textMessage, onSuccess: (msg) {
debugPrint("Mentioned users: ${msg.mentionedUsers}");
}, onError: (e) {});
// Get mentioned users from a message
List mentionedUsers = message.mentionedUsers;
// Check if logged-in user was mentioned
bool wasMentioned = message.hasMentionedMe ?? false;
// Fetch messages with mention tag info
MessagesRequest request = (MessagesRequestBuilder()
..uid = "UID"
..limit = 30
..mentionsWithTagInfo(true)
).build();
request.fetchPrevious(onSuccess: (messages) {}, onError: (e) {});
```
Mentions in messages enable users to refer to specific individuals within a conversation. This is done by using the `<@uid:UID>` format, where `UID` represents the user's unique identification.
Mentions are a powerful tool for enhancing communication in messaging platforms. They streamline interaction by allowing users to easily engage and collaborate with particular individuals, especially in group conversations.
**Available via:** SDK | [REST API](https://api-explorer.cometchat.com) | [UI Kits](/ui-kit/flutter/overview)
## Send Mentioned Messages
Every User object has a String unique identifier associated with them which can be found in a property called uid. To mention a user in a message, the message text should contain the uid in following format: `<@uid:UID_OF_THE_USER>`. For example, to mention the user with UID cometchat-uid-1 in a text message, your text should be "`<@uid:cometchat-uid-1>`"
```dart theme={null}
String receiverID = "UID";
User sender = User(name: "Sender", uid: "senderUID");
String messageText = "Hello, <@uid:cometchat-uid-1>";
String receiverType = CometChatReceiverType.user;
TextMessage textMessage = TextMessage(
text: messageText,
sender: sender,
receiverUid: receiverID,
receiverType: receiverType,
category: CometChatMessageCategory.message,
type: CometChatMessageType.text);
CometChat.sendMessage(textMessage, onSuccess:(TextMessage textMessage) {
print("Message sent successfully: ${textMessage.text}, mentioned users: ${textMessage.mentionedUsers}");
},
onError:(CometChatException e) {
print("Message sending failed with exception: $e");
}
);
```
```dart theme={null}
String receiverID = "GUID";
User sender = User(name: "Sender", uid: "senderUID");
String messageText = "Hello, <@uid:cometchat-uid-1>";
String receiverType = CometChatReceiverType.group;
TextMessage textMessage = TextMessage(
text: messageText,
sender: sender,
receiverUid: receiverID,
receiverType: receiverType,
category: CometChatMessageCategory.message,
type: CometChatMessageType.text);
CometChat.sendMessage(textMessage, onSuccess:(TextMessage textMessage) {
print("Message sent successfully: ${textMessage.text}, mentioned users: ${textMessage.mentionedUsers}");
},
onError:(CometChatException e) {
print("Message sending failed with exception: $e");
}
);
```
**On Success** — A `TextMessage` object containing all details of the sent message with mentions:
**TextMessage Object:**
| Parameter | Type | Description | Sample Value |
| -------------------- | ------- | -------------------------------------------------- | --------------------------------------------------------- |
| `id` | number | Unique message ID | `501` |
| `metadata` | object | Custom metadata attached to the message | `{}` |
| `receiver` | object | Receiver user object | [See below ↓](#fetch-mentions-send-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 | `0` |
| `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-mentions-send-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 | `0` |
| `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
| `text` | string | The text content of the message | `"Hello, <@uid:cometchat-uid-1>"` |
| `tags` | array | List of tags associated with the message | `[]` |
| `unreadRepliesCount` | number | Count of unread replies | `0` |
| `mentionedUsers` | array | List of mentioned users | [See below ↓](#fetch-mentions-send-mentionedusers-object) |
| `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` |
***
**`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` |
***
**`receiver` Object:**
| Parameter | Type | Description | Sample Value |
| --------------- | ------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `uid` | string | Unique identifier of the receiver | `"cometchat-uid-2"` |
| `name` | string | Display name of the receiver | `"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` |
***
**`mentionedUsers` Array (per item):**
| Parameter | Type | Description | Sample Value |
| --------------- | ------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `uid` | string | Unique identifier of the mentioned user | `"cometchat-uid-1"` |
| `name` | string | Display name of the mentioned 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` |
| Parameter | Type | Description | Sample Value |
| --------- | ------ | ---------------------------- | -------------------------------------------------------------- |
| `code` | string | Error code identifier | `"ERR_CHAT_API_FAILURE"` |
| `message` | string | Human-readable error message | `"Failed to send the message."` |
| `details` | string | Additional technical details | `"An unexpected error occurred while processing the request."` |
You can mention user in text message and media messages captions
## Mentioned Messages
By default, the SDK will fetch all the messages irrespective of the fact that the logged-in user is mentioned or not in the message. The SDK has other optional filters such as tag info and blocked info.
| Setting | Description | Default Value |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `mentionsWithTagInfo(bool value)` | If set to `true`, SDK will fetch a list of messages where users are mentioned & will also fetch the tags of the mentioned users. | false |
| `mentionsWithBlockedInfo(bool value)` | If set to `true`, SDK will fetch a list of messages where users are mentioned & will also fetch their blocked relationship with the logged-in user. | false |
## Mentions With Tag Info
To get a list of messages in a conversation where users are mentioned along with the tags of the mentioned users.
Relevant fields to access on returned messages and their mentioned users:
| Field | Property | Return Type | Description |
| ----------------------------- | ---------------- | -------------------------------------------- | --------------------------------------- |
| mentionedUsers | `mentionedUsers` | [`List`](/sdk/reference/entities#user) | Array of users mentioned in the message |
| tags (on each mentioned user) | `tags` | `List` | Tags associated with the mentioned user |
```dart theme={null}
String UID = "cometchat-uid-1";
MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..uid=UID
..mentionsWithTagInfo(true))
.build();
messagesRequest.fetchPrevious(onSuccess:(List messages) {
for (BaseMessage message in messages){
for (User user in message.mentionedUsers){
print("mentioned user tags: ${user.tags}");
}
}
},
onError: (CometChatException e) {
print("error: $e");
}
);
```
```dart theme={null}
String GUID = "cometchat-guid-1";
MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..guid=GUID
..mentionsWithTagInfo(true))
.build();
messagesRequest.fetchPrevious(onSuccess:(List messages) {
for (BaseMessage message in messages){
for (User user in message.mentionedUsers){
print("mentioned user tags: ${user.tags}");
}
}
},
onError: (CometChatException e) {
print("error: $e");
}
);
```
**On Success** — A `List` containing messages with mentioned users and their tag info (each item is a BaseMessage object):
**BaseMessage Object:**
| Parameter | Type | Description | Sample Value |
| -------------------- | ------ | -------------------------------------------------- | ------------------------------------------------------ |
| `id` | number | Unique message ID | `502` |
| `metadata` | object | Custom metadata attached to the message | `{}` |
| `receiver` | object | Receiver user object | [See below ↓](#fetch-mentions-taginfo-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 | `0` |
| `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-mentions-taginfo-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) | `0` |
| `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 | `0` |
| `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
| `unreadRepliesCount` | number | Count of unread replies | `0` |
| `quotedMessageId` | number | ID of the quoted message | `null` |
| `quotedMessage` | object | The quoted message object | `null` |
***
**`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 | `"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` |
***
**`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 | `"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` |
| 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 processing the request."` |
## Mentions With Blocked Info
To get a list of messages in a conversation where users are mentioned along with the blocked relationship of the mentioned users with the logged-in user.
Relevant fields to access on returned messages and their mentioned users:
| Field | Property | Return Type | Description |
| ------------------------------------- | ---------------- | -------------------------------------------- | ---------------------------------------------------------- |
| mentionedUsers | `mentionedUsers` | [`List`](/sdk/reference/entities#user) | Array of users mentioned in the message |
| blockedByMe (on each mentioned user) | `blockedByMe` | `bool` | Whether the logged-in user has blocked this mentioned user |
| hasBlockedMe (on each mentioned user) | `hasBlockedMe` | `bool` | Whether this mentioned user has blocked the logged-in user |
```dart theme={null}
String UID = "cometchat-uid-1";
MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..uid=UID
..mentionsWithBlockedInfo(true))
.build();
messagesRequest.fetchPrevious(onSuccess:(List messages) {
for (BaseMessage message in messages){
for (User user in message.mentionedUsers){
print("mentioned user has blocked me? ${user.hasBlockedMe}");
print("mentioned user is blocked by me? ${user.blockedByMe}");
}
}
},
onError: (CometChatException e) {
print("error: $e");
}
);
```
```dart theme={null}
String GUID = "cometchat-guid-1";
MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..guid=GUID
..mentionsWithBlockedInfo(true))
.build();
messagesRequest.fetchPrevious(onSuccess:(List messages) {
for (BaseMessage message in messages){
for (User user in message.mentionedUsers){
print("mentioned user has blocked me? ${user.hasBlockedMe}");
print("mentioned user is blocked by me? ${user.blockedByMe}");
}
}
},
onError: (CometChatException e) {
print("error: $e");
}
);
```
**On Success** — A `List` containing messages with mentioned users and their blocked relationship info (each item is a BaseMessage object):
**BaseMessage Object:**
| Parameter | Type | Description | Sample Value |
| -------------------- | ------ | -------------------------------------------------- | ---------------------------------------------------------- |
| `id` | number | Unique message ID | `503` |
| `metadata` | object | Custom metadata attached to the message | `{}` |
| `receiver` | object | Receiver user object | [See below ↓](#fetch-mentions-blockedinfo-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 | `0` |
| `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-mentions-blockedinfo-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) | `0` |
| `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 | `0` |
| `updatedAt` | number | Epoch timestamp when the message was last updated | `1745554729` |
| `unreadRepliesCount` | number | Count of unread replies | `0` |
| `quotedMessageId` | number | ID of the quoted message | `null` |
| `quotedMessage` | object | The quoted message object | `null` |
***
**`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 | `"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` |
***
**`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 | `"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` |
| 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 processing the request."` |
## Get Users Mentioned In a Particular Message
To retrieve the list of users mentioned in the particular message, you can use the `mentionedUsers` property on any `BaseMessage`. This property will return an array containing User objects of the mentioned users, or an empty array if no users were mentioned in the message.
```dart theme={null}
message.mentionedUsers
```
The `mentionedUsers` property returns a `List<`[`User`](/sdk/reference/entities#user)`>` objects.
## Check if Logged-in user has been mentioned
To check if the logged-in user has been mentioned in a particular message we can use the `hasMentionedMe` property on any `BaseMessage`. This property will return a boolean value, true if the logged-in user has been mentioned, otherwise `false`.
```dart theme={null}
message.hasMentionedMe
```
***
## Next Steps
Send text, media, and custom messages
Listen for incoming messages in real time
Add emoji reactions to messages
Organize conversations with message threads