Skip to main content
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.
  • User Mentions
  • Channel Mentions
Tag specific users in posts and comments with @username notation.

Mention Properties

PropertyTypeDescription
typeenumAlways "user" for user mentions
indexnumberStart index of the mention in text
userIdstringID of the mentioned user
lengthnumberLength of the mention text (excluding ”@” symbol)
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

  • Validate mention data before submitting content
  • Verify user IDs exist before creating mentions
  • Check text positions match mention metadata
  • Sanitize user input to prevent mention abuse
  • Provide visual feedback for mentions in UI
  • Make mentions clickable for better navigation
  • Show autocomplete suggestions during typing
  • Handle mention notifications appropriately
  • Cache user data for mention suggestions
  • Debounce search queries for better performance
  • Limit suggestion results to reasonable numbers
  • Index mention text for fast searching

Don'ts

  • Don’t mention users excessively - respect user attention
  • Don’t allow mention spam - implement rate limiting
  • Don’t mention in irrelevant contexts - keep mentions contextual
  • Don’t ignore user preferences - respect notification settings
  • Don’t expose private information in mention metadata
  • Don’t allow mentions of blocked users - check relationships
  • Don’t mention without permission in private channels
  • Don’t store sensitive data in mention metadata
  • Don’t forget mention click handlers in your UI
  • Don’t ignore mention parsing errors - handle gracefully
  • Don’t hard-code mention styling - make it customizable
  • Don’t skip mention validation - always verify data

​
Troubleshooting

Common causes:
  • Missing mentionUsers array in the parameter
  • Invalid user IDs in the mention list
  • User has disabled mention notifications
  • Network connectivity issues
Common causes:
  • Incorrect mention positions in metadata
  • Missing mention parsing in UI components
  • CSS styling issues
  • Metadata not matching actual text
Common causes:
  • No debouncing on search queries
  • Loading too many user suggestions
  • Inefficient mention parsing
  • Memory leaks in component state
Solutions:
// Implement debounced search
import { debounce } from 'lodash';

const debouncedSearch = debounce((query: string) => {
  searchUsers(query).then(setSuggestions);
}, 300);

// Limit results
const limitedSuggestions = suggestions.slice(0, 10);
Common causes:
  • Text modifications after mention creation
  • Incorrect index calculations
  • Unicode character handling issues
  • Concurrent text editing
Solutions:
// Always validate before submission
const validateMentionData = (text: string, mentions: AmityMention[]) => {
  for (const mention of mentions) {
    const start = mention.index;
    const end = start + mention.length + 1;
    const mentionText = text.substring(start, end);
    
    if (!mentionText.startsWith('@')) {
      throw new Error(`Invalid mention at position ${start}`);
    }
  }
  return true;
};

​
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