Mentions

Learn how to mention users in messages using the CometChat React Native SDK. Use the <@uid:UID> format to tag specific users in text and media message captions.

Quick Reference - Mention a user in a message:

// Use the format <@uid:UID> to mention users
let messageText = "Hello, <@uid:cometchat-uid-1>";
let textMessage = new CometChat.TextMessage("RECEIVER_ID", messageText, CometChat.RECEIVER_TYPE.USER);
CometChat.sendMessage(textMessage);

Available via: SDK | REST API | UI Kits

Mentions in messages enable users to refer to specific individual 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.

Send Mentioned Messages

To send a message with a mentioned user, you must follow a specific format: <@uid:UID>. For example, to mention the user with UID cometchat-uid-1 with the message “Hello,” your text would be “Hello, <@uid:cometchat-uid-1>”

To User

let receiverID = "UID";
let messageText = "Hello, <@uid:cometchat-uid-1>";
let receiverType = CometChat.RECEIVER_TYPE.USER;
let textMessage = new CometChat.TextMessage(
  receiverID,
  messageText,
  receiverType
);

CometChat.sendMessage(textMessage).then(
  (message) => {
    console.log("Message sent successfully:", message);
  },
  (error) => {
    console.log("Message sending failed with error:", error);
  }
);

To Group

let receiverID = "GUID";
let messageText = "Hello <@uid:cometchat-uid-1>";
let receiverType = CometChat.RECEIVER_TYPE.GROUP;
let textMessage = new CometChat.TextMessage(
  receiverID,
  messageText,
  receiverType
);

CometChat.sendMessage(textMessage).then(
  (message) => {
    console.log("Message sent successfully:", message);
  },
  (error) => {
    console.log("Message sending failed with error:", error);
  }
);

TypeScript (User)

let receiverID: string = "UID",
  messageText: string = "Hello <@uid:cometchat-uid-1>";
  receiverType: string = CometChat.RECEIVER_TYPE.USER,
  textMessage: CometChat.TextMessage = new CometChat.TextMessage(receiverID, messageText, receiverType);

CometChat.sendMessage(textMessage).then(
  (message: CometChat.TextMessage) => {
      console.log("Message sent successfully:", message);
  }, (error: CometChat.CometChatException) => {
      console.log("Message sending failed with error:", error);
  }
);

TypeScript (Group)

let receiverID: string = "GUID",
  messageText: string = "Hello world!",
  receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
  textMessage: CometChat.TextMessage = new CometChat.TextMessage(
    receiverID,
    messageText,
    receiverType
  );

CometChat.sendMessage(textMessage).then(
  (message: CometChat.TextMessage) => {
    console.log("Message sent successfully:", message);
  },
  (error: CometChat.CometChatException) => {
    console.log("Message sending failed with error:", error);
  }
);

Response

On Success — sendMessage() with mentions returns the sent message object with mentionedUsers populated:

Message Object:

Parameter	Type	Description	Sample Value
id	string	Unique message identifier	"25326"
conversationId	string	Conversation identifier	"cometchat-uid-6_user_cometchat-uid-7"
receiverId	string	Receiver’s UID	"cometchat-uid-7"
receiverType	string	Type of receiver	"user"
type	string	Message type	"text"
category	string	Message category	"message"
text	string	Message text with mention format	"Hello <@uid:cometchat-uid-7>, this is a test mention!"
sentAt	number	Unix timestamp when sent	1772006074
updatedAt	number	Unix timestamp when updated	1772006074
mentionedMe	boolean	Whether current user is mentioned	false
mentionedUsers	array	Users mentioned in message	See below ↓
sender	object	Sender user details	See below ↓
receiver	object	Receiver user details	See below ↓
data	object	Additional message data	See below ↓
reactions	array	Message reactions	[]

---

mentionedUsers Array (per item):

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
avatar	string	URL to user’s avatar	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"
status	string	User’s online status	"online"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772005334
hasBlockedMe	boolean	Whether user has blocked current user	false
blockedByMe	boolean	Whether current user blocked this user	false
deactivatedAt	number	Deactivation timestamp (0 if active)	0

---

sender Object:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-6"
name	string	User’s display name	"Ronald Jerry"
avatar	string	URL to user’s avatar	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"
status	string	User’s online status	"offline"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772004288
hasBlockedMe	boolean	Whether user has blocked current user	false
blockedByMe	boolean	Whether current user blocked this user	false
deactivatedAt	number	Deactivation timestamp (0 if active)	0
tags	array	User tags	[]

---

receiver Object:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
avatar	string	URL to user’s avatar	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"
status	string	User’s online status	"online"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772005334
hasBlockedMe	boolean	Whether user has blocked current user	false
blockedByMe	boolean	Whether current user blocked this user	false
deactivatedAt	number	Deactivation timestamp (0 if active)	0
tags	array	User tags	[]

---

data Object:

Parameter	Type	Description	Sample Value
text	string	Message text	"Hello <@uid:cometchat-uid-7>, this is a test mention!"
entities	object	Sender and receiver entities	See below ↓
mentions	object	Mentioned users map	See below ↓

---

data.entities Object:

Parameter	Type	Description	Sample Value
sender	object	Sender entity wrapper	See below ↓
receiver	object	Receiver entity wrapper	See below ↓

---

data.entities.sender Object:

Parameter	Type	Description	Sample Value
entityType	string	Type of entity	"user"
entity	object	User entity details	See below ↓

---

data.entities.sender.entity Object:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-6"
name	string	User’s display name	"Ronald Jerry"
avatar	string	User’s avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"
status	string	User’s online status	"offline"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772004288
tags	array	User tags	[]

---

data.entities.receiver Object:

Parameter	Type	Description	Sample Value
entityType	string	Type of entity	"user"
entity	object	User entity details	See below ↓

---

data.entities.receiver.entity Object:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
avatar	string	User’s avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"
status	string	User’s online status	"online"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772005334
conversationId	string	Conversation identifier	"cometchat-uid-6_user_cometchat-uid-7"
tags	array	User tags	[]

---

data.mentions Object:

Parameter	Type	Description	Sample Value
cometchat-uid-7	object	Mentioned user details keyed by UID	See below ↓

---

data.mentions["cometchat-uid-7"] Object:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
avatar	string	User’s avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"
status	string	User’s online status	"online"
role	string	User’s role	"default"
lastActiveAt	number	Last active timestamp	1772005334
conversationId	string	Conversation identifier	"cometchat-uid-6_user_cometchat-uid-7"

You can mention user in text message and media messages captions

Push Notifications & UI Rendering: While the message format uses <@uid:UID>, push notifications are sent with the parsed body containing the actual username — not the raw <@uid:> format. For UI rendering with the SDK, use message.getMentionedUsers() to get the mentioned user objects (which include both uid and name) and replace the <@uid:> tags in your message bubble accordingly. If you’re using a UI Kit, this is handled automatically.

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 tags and blocked relationships.

Setting	Description
mentionsWithTagInfo(boolean 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. Default value = false
mentionsWithBlockedInfo(boolean 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. Default value = false

Mentions With Tag Info

To get a list of messages in a conversation where users are mentioned along with the user tags of the mentioned users.

To User

let UID = "UID";
let limit = 30;

var messagesRequest = new CometChat.MessagesRequestBuilder()
  .setUID(UID)
  .setLimit(limit)
  .mentionsWithTagInfo(true)
  .build();

messagesRequest.fetchPrevious().then(
  (messages) => {
    messages.forEach((eachMessage) => {
      eachMessage.getMentionedUsers().forEach((eachMentionedUser) => {
        console.log(eachMentionedUser.getTags());
      });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

To Group

let GUID = "GUID";
let limit = 30;

var messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID(GUID)
  .setLimit(limit)
  .mentionsWithTagInfo(true)
  .build();

messagesRequest.fetchPrevious().then(
  (messages) => {
    messages.forEach((eachMessage) => {
      eachMessage.getMentionedUsers().forEach((eachMentionedUser) => {
        console.log(eachMentionedUser.getTags());
      });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript (User)

let UID: string = "UID",
  limit: number = 30,
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setUID(UID)
      .setLimit(limit)
      .mentionsWithTagInfo(true)
      .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    messages.forEach((eachMessage: CometChat.BaseMessage) => {
      eachMessage
        .getMentionedUsers()
        .forEach((eachMentionedUser: CometChat.User) => {
          console.log(eachMentionedUser.getTags());
        });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript (Group)

let GUID: string = "GUID",
  limit: number = 30,
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setGUID(GUID)
      .setLimit(limit)
      .mentionsWithTagInfo(true)
      .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    messages.forEach((eachMessage: CometChat.BaseMessage) => {
      eachMessage
        .getMentionedUsers()
        .forEach((eachMentionedUser: CometChat.User) => {
          console.log(eachMentionedUser.getTags());
        });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

Response

On Success — mentionsWithTagInfo(true) returns mentioned users with their tags:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
tags	array	User’s tags	["vip"]

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.

To User

let UID = "UID";
let limit = 30;
var messagesRequest = new CometChat.MessagesRequestBuilder()
  .setUID(UID)
  .setLimit(limit)
  .mentionsWithBlockedInfo(true)
  .build();

messagesRequest.fetchPrevious().then(
  (messages) => {
    messages.forEach((eachMessage) => {
      eachMessage.getMentionedUsers().forEach((eachMentionedUser) => {
        console.log("blockedByMe: " + eachMentionedUser.getBlockedByMe());
        console.log("hasBlockedMe: " + eachMentionedUser.getHasBlockedMe());
      });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

To Group

let GUID = "GUID";
let limit = 30;

var messagesRequest = new CometChat.MessagesRequestBuilder()
  .setGUID(GUID)
  .setLimit(limit)
  .mentionsWithBlockedInfo(true)
  .build();

messagesRequest.fetchPrevious().then(
  (messages) => {
    messages.forEach((eachMessage) => {
      eachMessage.getMentionedUsers().forEach((eachMentionedUser) => {
        console.log("blockedByMe: " + eachMentionedUser.getBlockedByMe());
        console.log("hasBlockedMe: " + eachMentionedUser.getHasBlockedMe());
      });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript (User)

let UID: string = "UID",
  limit: number = 30,
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setUID(UID)
      .setLimit(limit)
      .mentionsWithBlockedInfo(true)
      .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    messages.forEach((eachMessage: CometChat.BaseMessage) => {
      eachMessage
        .getMentionedUsers()
        .forEach((eachMentionedUser: CometChat.User) => {
          console.log("blockedByMe: " + eachMentionedUser.getBlockedByMe());
          console.log("hasBlockedMe: " + eachMentionedUser.getHasBlockedMe());
        });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

TypeScript (Group)

let GUID: string = "GUID",
  limit: number = 30,
  messagesRequest: CometChat.MessagesRequest =
    new CometChat.MessagesRequestBuilder()
      .setGUID(GUID)
      .setLimit(limit)
      .mentionsWithBlockedInfo(true)
      .build();

messagesRequest.fetchPrevious().then(
  (messages: CometChat.BaseMessage[]) => {
    messages.forEach((eachMessage: CometChat.BaseMessage) => {
      eachMessage
        .getMentionedUsers()
        .forEach((eachMentionedUser: CometChat.User) => {
          console.log("blockedByMe: " + eachMentionedUser.getBlockedByMe());
          console.log("hasBlockedMe: " + eachMentionedUser.getHasBlockedMe());
        });
    });
  },
  (error) => {
    console.log("Message fetching failed with error:", error);
  }
);

Response

On Success — mentionsWithBlockedInfo(true) returns mentioned users with blocked relationship info:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
blockedByMe	boolean	Whether current user blocked this user	false
hasBlockedMe	boolean	Whether user has blocked current user	false

Get Users Mentioned In a Particular Message

To retrieve the list of users mentioned in the particular message, you can use the message.getMentionedUsers() method. This method will return an array containing the mentioned users, or an empty array if no users were mentioned in the message.

message.getMentionedUsers();

Response

On Success — getMentionedUsers() returns an array of mentioned user objects:

Parameter	Type	Description	Sample Value
uid	string	User’s unique identifier	"cometchat-uid-7"
name	string	User’s display name	"Henry Marino"
avatar	string	URL to user’s avatar	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"
status	string	User’s online status	"online"
blockedByMe	boolean	Whether current user blocked this user	false
hasBlockedMe	boolean	Whether user has blocked current user	false

Best Practices

Use correct mention format

Always use the <@uid:UID> format when mentioning users. The UID must exactly match the user’s unique identifier in CometChat. Incorrect UIDs will not resolve to a valid mention.

Validate UIDs before sending

Before sending a message with mentions, verify that the UIDs you are referencing exist in your CometChat app. Mentioning non-existent UIDs will not throw an error, but the mention will not resolve to a user on the recipient’s end.

Combine mentions with tag and blocked info when needed

Use mentionsWithTagInfo(true) and mentionsWithBlockedInfo(true) on your MessagesRequestBuilder when you need to display additional context about mentioned users, such as their roles (via tags) or blocked status. Avoid enabling these filters unnecessarily to reduce payload size.

Handle mentions in both text and media messages

Mentions are supported in text messages and media message captions. Ensure your UI handles rendering mentions consistently across both message types.

Troubleshooting

Mentions not appearing in received messages

Ensure you are using the correct <@uid:UID> format. The UID must be wrapped exactly as <@uid:your-uid-here>. Also verify that the mentioned user exists in your CometChat app. Use message.getMentionedUsers() to confirm the SDK parsed the mentions correctly.

getMentionedUsers() returns an empty array

This typically means the mention format in the message text is incorrect or the UID does not match any registered user. Double-check the message text for proper <@uid:UID> syntax and ensure there are no extra spaces or typos in the UID.

Tag or blocked info not returned for mentioned users

Make sure you have set mentionsWithTagInfo(true) or mentionsWithBlockedInfo(true) on your MessagesRequestBuilder before calling fetchPrevious(). These filters are disabled by default.

Mentions not working in media message captions

Verify that you are setting the caption text with the <@uid:UID> format on the media message object. Mentions in captions follow the same format as text messages.

Next Steps

Send a Message

Learn how to send text, media, and custom messages to users and groups.

Receive Messages

Set up real-time message listeners and fetch message history.

Reactions

Add emoji reactions to messages for richer user interactions.

Threaded Messages

Organize conversations with threaded replies on messages.