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

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

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

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

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.