> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-ios-ui-kit-sdk-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions

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

<Info>
  **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](/sdk/ios/send-message) · [Receive Message](/sdk/ios/receive-message) · [Messaging Overview](/sdk/ios/messaging-overview)
</Info>

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

<Tabs>
  <Tab title="Swift (User)">
    ```swift theme={null}
    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)")
    }
    ```
  </Tab>

  <Tab title="Swift (Group)">
    ```swift theme={null}
    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)")
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads - Send Mentioned Message (User)">
  <Tabs>
    <Tab title="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>`                              |
    </Tab>

    <Tab title="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"` |
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Sample Payloads - Send Mentioned Message (Group)">
  <Tabs>
    <Tab title="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!"` |
    </Tab>

    <Tab title="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"` |
    </Tab>
  </Tabs>
</Accordion>

<Note>
  You can mention users in text messages and media message captions.
</Note>

***

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

<Tabs>
  <Tab title="Swift (User)">
    ```swift theme={null}
    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)")
    }
    ```
  </Tab>

  <Tab title="Swift (Group)">
    ```swift theme={null}
    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)")
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads - Fetch Mentions with Tag Info">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter           | Type     | Value               |
      | ------------------- | -------- | ------------------- |
      | uid                 | `String` | `"cometchat-uid-2"` |
      | limit               | `Int`    | `50`                |
      | mentionsWithTagInfo | `Bool`   | `true`              |
    </Tab>

    <Tab title="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"]` |
    </Tab>
  </Tabs>
</Accordion>

### Mentions With Blocked Info

<Tabs>
  <Tab title="Swift (User)">
    ```swift theme={null}
    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)")
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads - Fetch Mentions with Blocked Info">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter               | Type     | Value               |
      | ----------------------- | -------- | ------------------- |
      | uid                     | `String` | `"cometchat-uid-2"` |
      | limit                   | `Int`    | `50`                |
      | mentionsWithBlockedInfo | `Bool`   | `true`              |
    </Tab>

    <Tab title="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`             |
    </Tab>
  </Tabs>
</Accordion>

***

## Get Users Mentioned In a Message

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

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let mentionedUsers = message.mentionedUsers  // Returns [User]
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let wasMentioned = message.mentionedMe  // Returns Bool
    ```
  </Tab>
</Tabs>

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