> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions

> Send messages with user mentions, retrieve mentioned users, and filter messages by mention metadata using the CometChat iOS SDK.

<Accordion title="AI Integration Quick Reference">
  ```swift theme={null}
  // Send a message with a mention (use <@uid:UID> format)
  let msg = TextMessage(receiverUid: "UID", text: "Hello <@uid:cometchat-uid-1>", receiverType: .user)
  CometChat.sendTextMessage(message: msg) { message in } onError: { error in }

  // Get mentioned users from a message
  let mentionedUsers = message.mentionedUsers  // Returns [User]

  // Check if logged-in user was mentioned
  let wasMentioned = message.mentionedMe  // Returns Bool

  // Fetch messages with mention tag info
  let request = MessagesRequest(builder: MessagesRequest.MessageRequestBuilder()
      .set(uid: "UID").set(limit: 30).mentionsWithTagInfo(true))
  request.fetchPrevious { messages in } onError: { error in }
  ```
</Accordion>

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>

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

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

***

## Get Users Mentioned In a Message

To retrieve the list of users mentioned in a particular message. Returns an array of [`User`](/sdk/reference/entities#user) objects:

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Send Messages" icon="paper-plane" href="/sdk/ios/send-message">
    Send text, media, and custom messages
  </Card>

  <Card title="Receive Messages" icon="envelope-open" href="/sdk/ios/receive-message">
    Listen for incoming messages in real time
  </Card>

  <Card title="Reactions" icon="face-smile" href="/sdk/ios/reactions">
    Add emoji reactions to messages
  </Card>

  <Card title="Threaded Messages" icon="comments" href="/sdk/ios/threaded-messages">
    Organize conversations with message threads
  </Card>
</CardGroup>