Mentions - CometChat Docs

AI Integration Quick Reference

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

// 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<User> 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 | UI Kits

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

Flutter (User)
Flutter (Group)

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");
  }
);

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");
  }
);

Response

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

Error

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<User>`	Array of users mentioned in the message
tags (on each mentioned user)	`tags`	`List<String>`	Tags associated with the mentioned user

Flutter (User)
Flutter (Group)

String UID = "cometchat-uid-1";

MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..uid=UID
..mentionsWithTagInfo(true))
.build();

messagesRequest.fetchPrevious(onSuccess:(List<BaseMessage> messages) {
    for (BaseMessage message in messages){
      for (User user in message.mentionedUsers){
        print("mentioned user tags: ${user.tags}");
      }
    }
  },
		onError: (CometChatException e) {
    print("error: $e");
  }
);

String GUID = "cometchat-guid-1";

MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..guid=GUID
..mentionsWithTagInfo(true))
.build();

messagesRequest.fetchPrevious(onSuccess:(List<BaseMessage> messages) {
    for (BaseMessage message in messages){
      for (User user in message.mentionedUsers){
        print("mentioned user tags: ${user.tags}");
      }
    }
  },
		onError: (CometChatException e) {
    print("error: $e");
  }
);

Response

On Success — A List<BaseMessage> 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 ↓
`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 ↓
`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`

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

Flutter (User)
Flutter (Group)

String UID = "cometchat-uid-1";

MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..uid=UID
..mentionsWithBlockedInfo(true))
.build();

messagesRequest.fetchPrevious(onSuccess:(List<BaseMessage> 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");
  }
);

String GUID = "cometchat-guid-1";

MessagesRequest messagesRequest = (MessagesRequestBuilder()
..limit=50
..guid=GUID
..mentionsWithBlockedInfo(true))
.build();

messagesRequest.fetchPrevious(onSuccess:(List<BaseMessage> 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");
  }
);

Response

On Success — A List<BaseMessage> 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 ↓
`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 ↓
`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`

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

message.mentionedUsers

The mentionedUsers property returns a List<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

message.hasMentionedMe

Next Steps

Send Messages

Send text, media, and custom messages

Receive Messages

Listen for incoming messages in real time

Reactions

Add emoji reactions to messages

Threaded Messages

Organize conversations with message threads

​Send Mentioned Messages

​Mentioned Messages

​Mentions With Tag Info

​Mentions With Blocked Info

​Get Users Mentioned In a Particular Message

​Check if Logged-in user has been mentioned

​Next Steps

Send Messages

Receive Messages

Reactions

Threaded Messages

Send Mentioned Messages

Mentioned Messages

Mentions With Tag Info

Mentions With Blocked Info

Get Users Mentioned In a Particular Message

Check if Logged-in user has been mentioned

Next Steps