Mentions - CometChat Docs

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
To Group
TypeScript (User)
TypeScript (Group)

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

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

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

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
To Group
TypeScript (User)
TypeScript (Group)

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

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

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

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
To Group
TypeScript (User)
TypeScript (Group)

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

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

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

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.

​Send Mentioned Messages

​Mentioned Messages

​Mentions With Tag Info

​Mentions With Blocked Info

​Get Users Mentioned In a Particular Message

​Best Practices

​Troubleshooting

​Next Steps

Send a Message

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

Best Practices

Troubleshooting

Next Steps