> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions

> Attach user mention payloads and mention metadata when creating or editing posts, comments, and messages.

Mentions are attached to content creation or edit calls. They use two pieces of data: `mentionees` tells Social+ which users or channel are mentioned, and `metadata` stores the text ranges your UI can use to render the highlighted mention text.

<Note>
  User mentions are available on posts, comments, and messages. Channel mentions are message-only.
</Note>

## Platform Surface

| Platform   | Mentionees payload                                            | Mention metadata helper                          |
| ---------- | ------------------------------------------------------------- | ------------------------------------------------ |
| TypeScript | `mentionees: [{ type: "user", userIds: [...] }]`              | Plain `metadata` object with `mentioned` entries |
| iOS        | `AmityMentioneesBuilder`                                      | `AmityMetadataMapper.metadata(mentions:)`        |
| Android    | `mentionUserIds` on post APIs or `mentionUsers()` on builders | `AmityMentionMetadataCreator`                    |
| Flutter    | `mentionUsers()` on builders                                  | `AmityMentionMetadataCreator`                    |

## Parameters

| Parameter                      | Required                  | Description                                                                                                                 |
| ------------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `text`                         | Yes                       | Content text that includes the mention display text, such as `@alex`.                                                       |
| `mentionees` / mention builder | Yes for mention behavior  | Users or channel being mentioned. Posts and comments support user mentionees; messages support user and channel mentionees. |
| `metadata`                     | Recommended for rendering | Metadata object containing mention text ranges under `mentioned`.                                                           |
| `type`                         | Yes in metadata           | Use `user` for user mentions or `channel` for message channel mentions.                                                     |
| `index`                        | Yes in metadata           | Zero-based index where the mention starts in the content text.                                                              |
| `length`                       | Yes in metadata           | Length of the display name after the `@` character. For `@alex`, use `4`.                                                   |
| `userId`                       | User mentions only        | ID of the mentioned user.                                                                                                   |

## Create Content With A User Mention

The examples below create a community text post that mentions one user. Use the same mentionee and metadata pattern when creating comments or messages with the SDK-specific creation API.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { PostRepository } from "@amityco/ts-sdk";

  const text = "Hello @alex";
  const metadata = {
    mentioned: [
      {
        type: "user",
        userId,
        index: 6,
        length: 4,
      },
    ],
  };

  const { data: post } = await PostRepository.createPost({
    targetType: "community",
    targetId: communityId,
    data: { text },
    metadata,
    mentionees: [{ type: "user", userIds: [userId] }],
  });
  ```

  ```swift iOS theme={null}
  let text = "Hello @alex"
  let mention = AmityMention(
      type: .user,
      index: 6,
      length: 4,
      userId: userId
  )
  let metadata = AmityMetadataMapper.metadata(mentions: [mention])

  let mentionees = AmityMentioneesBuilder()
  mentionees.mentionUsers(userIds: [userId])

  let builder = AmityTextPostBuilder()
  builder.setText(text)

  let post = try await postRepository.createTextPost(
      builder,
      targetId: communityId,
      targetType: .community,
      metadata: metadata,
      mentionees: mentionees
  )
  ```

  ```kotlin Android theme={null}
  import com.amity.socialcloud.sdk.helper.core.mention.AmityMentionMetadata
  import com.amity.socialcloud.sdk.helper.core.mention.AmityMentionMetadataCreator

  val text = "Hello @alex"
  val mentionMetadata = AmityMentionMetadata.USER(
      userId = userId,
      index = 6,
      length = 4
  )
  val metadata = AmityMentionMetadataCreator(
      mentionMetaData = listOf(mentionMetadata)
  ).create()

  postRepository.createTextPost(
      targetType = AmityPost.TargetType.COMMUNITY,
      targetId = communityId,
      text = text,
      metadata = metadata,
      mentionUserIds = setOf(userId)
  )
      .subscribe(
          { post -> showSuccessMessage(post.getPostId()) },
          { error -> handleGeneralError(error) }
      )
  ```

  ```dart Flutter theme={null}
  final text = 'Hello @alex';
  final metadata = AmityMentionMetadataCreator([
    AmityUserMentionMetadata(
      userId: userId,
      index: 6,
      length: 4,
    ),
  ]).create();

  final creator = AmitySocialClient.newPostRepository()
      .createPost()
      .targetCommunity(communityId)
      .text(text);

  creator.mentionUsers([userId]);
  creator.metadata(metadata);

  final post = await creator.createTextPost();
  ```
</CodeGroup>

## Rendering Mentions

Use the content text and `metadata.mentioned` entries together when rendering. The `mentionees` payload identifies mentioned users or channel targets, while `metadata` identifies where the mention appears in the text.

| Metadata field | Meaning                                   |
| -------------- | ----------------------------------------- |
| `type`         | `user` or `channel`                       |
| `index`        | Start position of the mention in the text |
| `length`       | Display-name length after `@`             |
| `userId`       | Present for user mentions                 |

## Notes

* Keep `metadata` and `mentionees` in sync. A highlighted `@alex` without a matching mentionee payload is only display metadata.
* Use the user IDs returned by your mention picker. Display names can change, but user IDs are the stable mention target.
* For messages, channel mentions use a channel mentionee entry. Posts and comments use user mentionees.
* Existing content models expose mention information after creation; use the model returned by the SDK or a fresh query when your UI needs server-confirmed state.

## Related Topics

<CardGroup cols={3}>
  <Card title="Text Posts" icon="pen-line" href="/social-plus-sdk/social/content-management/posts/creation/text-post">
    Create text posts that can carry mention metadata
  </Card>

  <Card title="Text Comment" icon="message-square" href="/social-plus-sdk/social/content-management/comments/creation/text-comment">
    Add user mentions to comments and replies
  </Card>

  <Card title="Send A Message" icon="message-circle" href="/social-plus-sdk/chat/messaging-features/message-creation/send-a-message">
    Use user and channel mentions in chat messages
  </Card>
</CardGroup>