Mentions

Guide to mentioning users in messages using the CometChat iOS SDK with mention formatting and retrieval.

Quick Reference for AI Agents & Developers

• Mention format: <@uid:USER_UID> in message text (e.g., "Hello <@uid:cometchat-uid-1>")
• Get mentioned users: message.mentionedUsers returns array of mentioned User objects
• Check if mentioned: message.mentionedMe returns Bool
• Fetch with tag info: MessagesRequest.MessageRequestBuilder().mentionsWithTagInfo(true).build()
• Related: Send Message · Receive Message · Messaging Overview

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.

Mention Format

Format	Example
<@uid:USER_UID>	<@uid:cometchat-uid-1>

Example message text with mention:

"Hello <@uid:cometchat-uid-1>, how are you?"

---

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

Swift (User)

let messageText = "Hello <@uid:cometchat-uid-1>, how are you?"
let textMessage = TextMessage(receiverUid: "cometchat-uid-2", text: messageText, receiverType: .user)

CometChat.sendTextMessage(message: textMessage) { message in
    print("Mentioned users: \(message.mentionedUsers)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Swift (Group)

let messageText = "Hey <@uid:cometchat-uid-2>, check this out!"
let textMessage = TextMessage(receiverUid: "cometchat-guid-1", text: messageText, receiverType: .group)

CometChat.sendTextMessage(message: textMessage) { message in
    print("Mentioned users: \(message.mentionedUsers)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Sample Payloads - Send Mentioned Message (User)

Request

Method: CometChat.sendTextMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	.user
text	String	"Hello <@uid:cometchat-uid-2>, how are you?"
mentionFormat	String	<@uid:USER_UID>

Success Response

Message Properties:

Parameter	Type	Value
id	Int	38231
text	String	"Hello <@uid:cometchat-uid-2>, how are you?"
senderUid	String	"cometchat-uid-2"
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
sentAt	Int	1772028884

Mentioned Users:

Index	UID	Name
0	"cometchat-uid-2"	"George Alan"

Sample Payloads - Send Mentioned Message (Group)

Request

Method: CometChat.sendTextMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-guid-1"
receiverType	CometChat.ReceiverType	.group
text	String	"Hey <@uid:cometchat-uid-2>, check this out!"

Success Response

Message Properties:

Parameter	Type	Value
id	Int	38232
text	String	"Hey <@uid:cometchat-uid-2>, check this out!"
senderUid	String	"cometchat-uid-2"
receiverUid	String	"cometchat-guid-1"
receiverType	CometChat.ReceiverType	1 (.group)
sentAt	Int	1772028886

Mentioned Users:

Index	UID	Name
0	"cometchat-uid-2"	"George Alan"

You can mention users in text messages and media message captions.

---

Fetch Mentioned Messages

By default, the SDK will fetch all messages irrespective of whether the logged-in user is mentioned or not. The SDK allows you to fetch messages with additional mention information.

Setting	Description
mentionsWithTagInfo(true)	Fetch messages with mentioned users’ tags
mentionsWithBlockedInfo(true)	Fetch messages with blocked relationship info

Mentions With Tag Info

Swift (User)

let messagesRequest = MessagesRequest(builder: MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-2")
    .set(limit: 50)
    .mentionsWithTagInfo(true))

messagesRequest.fetchPrevious { messages in
    for message in messages ?? [] {
        for user in message.mentionedUsers {
            print("User tags: \(user.tags)")
        }
    }
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Swift (Group)

let messagesRequest = MessagesRequest(builder: MessagesRequest.MessageRequestBuilder()
    .set(guid: "cometchat-guid-1")
    .set(limit: 50)
    .mentionsWithTagInfo(true))

messagesRequest.fetchNext { messages in
    for message in messages ?? [] {
        for user in message.mentionedUsers {
            print("User tags: \(user.tags)")
        }
    }
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Sample Payloads - Fetch Mentions with Tag Info

Request

Method: MessagesRequest.fetchPrevious()

Parameter	Type	Value
uid	String	"cometchat-uid-2"
limit	Int	50
mentionsWithTagInfo	Bool	true

Success Response

Response Summary:

Parameter	Type	Value
messagesCount	Int	6
withTagInfo	Bool	true
withBlockedInfo	Bool	false

Mentioned User with Tag Info:

Parameter	Type	Value
uid	String	"cometchat-uid-1"
name	String	"John Doe"
tags	[String]	["vip", "premium"]

Mentions With Blocked Info

Swift (User)

let messagesRequest = MessagesRequest(builder: MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-2")
    .set(limit: 50)
    .mentionsWithBlockedInfo(true))

messagesRequest.fetchPrevious { messages in
    for message in messages ?? [] {
        for user in message.mentionedUsers {
            print("Has blocked me: \(user.hasBlockedMe)")
            print("Blocked by me: \(user.blockedByMe)")
        }
    }
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Sample Payloads - Fetch Mentions with Blocked Info

Request

Method: MessagesRequest.fetchPrevious()

Parameter	Type	Value
uid	String	"cometchat-uid-2"
limit	Int	50
mentionsWithBlockedInfo	Bool	true

Success Response

Response Summary:

Parameter	Type	Value
messagesCount	Int	6
withTagInfo	Bool	false
withBlockedInfo	Bool	true

Mentioned User with Blocked Info:

Parameter	Type	Value
uid	String	"cometchat-uid-1"
name	String	"John Doe"
hasBlockedMe	Bool	false
blockedByMe	Bool	false

---

Get Users Mentioned In a Message

To retrieve the list of users mentioned in a particular message:

Swift

let mentionedUsers = message.mentionedUsers  // Returns [User]

Mentioned Users Array:

Index	UID	Name
0	"cometchat-uid-1"	"John Doe"
1	"cometchat-uid-3"	"Jane Smith"

---

Check if Logged-in User Was Mentioned

To check if the logged-in user has been mentioned in a particular message:

Swift

let wasMentioned = message.mentionedMe  // Returns Bool

Property	Type	Description
mentionedMe	Bool	true if logged-in user was mentioned

---

Mentioned User Properties

Property	Type	Description
uid	String	Unique user identifier
name	String	User’s display name
avatar	String?	User’s avatar URL
tags	[String]	User’s tags (with mentionsWithTagInfo)
hasBlockedMe	Bool	Has user blocked logged-in user (with mentionsWithBlockedInfo)
blockedByMe	Bool	Is user blocked by logged-in user (with mentionsWithBlockedInfo)