Mentions allow users to tag other users in messages, comments, and posts. It’s a powerful tool for fostering engagement and collaboration within your social application, enabling users to directly alert others to new content or important updates.
Mention Support: User mentions are supported in posts, comments, and messages. Channel mentions are available in messages only.

​
Key Features

User Mentions

Tag specific users with @username notation for direct engagement

Channel Mentions

Mention entire channels to notify all members (messages only)

Smart Notifications

Automatic push notifications alert mentioned users instantly

Flexible Structure

Customizable mention data structure for advanced use cases

​
Where Mentions Work

Posts

Mention users in community posts to boost engagement and start conversations

Comments

Tag users in comment threads for focused discussions

Messages

Direct mentions in chat messages, including channel-wide mentions
Upon creating a model above (a post, comment, or message) with a mention, you can include a JSON object in the metadata parameter. The metadata represents the mentioned object, which depends on the design of your data structure. However, we provide a default structure to help you create the mentioned metadata. To ensure prompt notification of the person mentioned, it’s important to provide the list of user IDs for the mentioned user parameter. This will help ensure that the mentioned users are notified and able to engage with the content.
  • mentionUsers(userIds) - In order to mention users and notify specific users. This function supports all mentionable models.
  • mentionChannel(channelId) - In order to mention and notify the whole channel. This function supports only a message model.
  • metadata - a free-form JSON object that can accommodate any information regarding the mentioned users. Our default structure for representing mentions is also in the metadata property.

​
Default Mention Data Structure

To represent mentions using our structure, you will need to utilize the AmityMention object. This object can be created during mentionable model creation, as well as during rendering.
Tag specific users in posts and comments with @username notation.

Mention Properties

Index Calculation: The length property doesn’t include the ”@” symbol. For “@alice”, the length is 5, not 6.

​
Creating Mention Metadata

Below is an example to create a comment with mentions by using our default mention metadata structure: 
import AmitySDK

func createCommentWithMentionExample() {
    // 1. We will create a comment containing this text.
    let text = "Hi @john and @alice."
    // To add mention to a comment, we need extra steps.
    // In this example, we want to mention two users "john" and "alice".
    //
    // 2. We create metadata that contains mention object, via AmityMentionMapper helper class.
    //
    // Notice how `index` and `length` is set.
    let metadata = AmityMentionMapper.metadata(from: [
        AmityMention(type: .user, index: 3, length: 4, userId: "<john-user-id>"),
        AmityMention(type: .user, index: 13, length: 5, userId: "<alice-user-id>")
    ])
    // 3. We create mentionees.
    let mentionees = AmityMentioneesBuilder()
    mentionees.mentionUsers(userIds: ["<john-user-id>", "<alice-user-id>"])
    // Finally we pass (1) (2) and (3) to create a comment with mention.
    
    let createOptions = AmityCommentCreateOptions(referenceId: "post-id", referenceType: .post, text: text, parentId: nil, metadata: metadata, mentioneeBuilder: mentionees)
    commentRepository.createComment(with: createOptions) { comment, error in
        // Comment
    }
}

​
Parsing and Displaying Mentions

As we mentioned we provided the flexibility for you to define your own mention object data structure to represent mentions. You can use the default data structure provided by the SDK to render mentions in your application, which can be accessed through the helper class. This allows you to easily retrieve mentions and render them. The mentionable model contains properties related to the mentioned feature:
  • mentionUsers - The AmityUser object array contains details about users mentioned in the current content.
  • metadata - a free-form JSON object that can accommodate any information regarding the mentioned users. Our predefined structure for representing mentions is also in the metadata property.
Below is an example to render mentions in a comment by using our default mention data structure: 
import AmitySDK

func createCommentWithMentionExample() {
    // 1. We will create a comment containing this text.
    let text = "Hi @john and @alice."
    // To add mention to a comment, we need extra steps.
    // In this example, we want to mention two users "john" and "alice".
    //
    // 2. We create metadata that contains mention object, via AmityMentionMapper helper class.
    //
    // Notice how `index` and `length` is set.
    let metadata = AmityMentionMapper.metadata(from: [
        AmityMention(type: .user, index: 3, length: 4, userId: "<john-user-id>"),
        AmityMention(type: .user, index: 13, length: 5, userId: "<alice-user-id>")
    ])
    // 3. We create mentionees.
    let mentionees = AmityMentioneesBuilder()
    mentionees.mentionUsers(userIds: ["<john-user-id>", "<alice-user-id>"])
    // Finally we pass (1) (2) and (3) to create a comment with mention.
    
    let createOptions = AmityCommentCreateOptions(referenceId: "post-id", referenceType: .post, text: text, parentId: nil, metadata: metadata, mentioneeBuilder: mentionees)
    commentRepository.createComment(with: createOptions) { comment, error in
        // Comment
    }
}

​
Best Practices

Do's

Don'ts

​
Troubleshooting

​
Next Steps

Posts

Learn about mentions in posts

Comments

Implement mentions in comments

Messages

Add mentions to chat messages

Push Notifications

Set up mention notifications