Skip to main content

​
Mentions in Posts

Mentions enable users to tag other community members in posts, creating direct engagement opportunities and enhancing social interaction. The social.plus SDK provides comprehensive mention functionality with metadata support for custom rendering and notification systems.

​
Overview

Enhanced Engagement

Direct user engagement through mentions increases interaction and community building

Custom Rendering

Flexible metadata system supports custom mention display and interaction patterns

​
Mention Features

FeatureDescriptionBenefit
User TaggingTag specific users in post contentDirect engagement
Metadata SupportCustom rendering informationFlexible UI design
Notification IntegrationAutomatic notifications for mentioned usersReal-time engagement
ValidationVerify user existence and permissionsData integrity
Update SupportModify mentions in existing postsContent maintenance

​
Create Post with Mentions

Include user mentions when creating new posts with comprehensive metadata for custom rendering.
  • iOS
  • Android
  • TypeScript
  • Flutter
import AmitySDK

class PostMentionManager {
    private let client: AmityClient
    
    init(client: AmityClient) {
        self.client = client
    }
    
    // Create text post with mentions
    func createTextPostWithMentions(
        text: String,
        mentionedUserIds: [String],
        communityId: String? = nil,
        completion: @escaping (Result<AmityPost, Error>) -> Void
    ) {
        // Build mention metadata
        let mentionMetadata = buildMentionMetadata(text: text, userIds: mentionedUserIds)
        
        let builder = AmityTextPostBuilder()
            .setText(text)
            .setMentionUsers(mentionedUserIds)
            .setMetadata(mentionMetadata)
        
        let repository = AmityPostRepository(client: client)
        
        if let communityId = communityId {
            repository.createPost(builder, targetId: communityId, targetType: .community)
                .subscribe { result in
                    completion(result)
                }
        } else {
            repository.createPost(builder, targetType: .user)
                .subscribe { result in
                    completion(result)
                }
        }
    }
    
    // Build mention metadata for rendering
    private func buildMentionMetadata(text: String, userIds: [String]) -> [String: Any] {
        var mentions: [[String: Any]] = []
        
        for userId in userIds {
            // Find mention positions in text
            let mentionPattern = "@\(userId)"
            let ranges = text.ranges(of: mentionPattern)
            
            for range in ranges {
                mentions.append([
                    "userId": userId,
                    "type": "user",
                    "index": text.distance(from: text.startIndex, to: range.lowerBound),
                    "length": mentionPattern.count
                ])
            }
        }
        
        return [
            "mentioned": mentions
        ]
    }
    
    // Create post with advanced mention formatting
    func createPostWithFormattedMentions(
        text: String,
        mentions: [(userId: String, displayName: String, range: NSRange)],
        communityId: String? = nil
    ) {
        let userIds = mentions.map { $0.userId }
        
        // Build rich metadata
        let mentionObjects = mentions.map { mention in
            return [
                "userId": mention.userId,
                "displayName": mention.displayName,
                "type": "user",
                "index": mention.range.location,
                "length": mention.range.length
            ]
        }
        
        let metadata = [
            "mentioned": mentionObjects,
            "version": "1.0"
        ]
        
        let builder = AmityTextPostBuilder()
            .setText(text)
            .setMentionUsers(userIds)
            .setMetadata(metadata)
        
        let repository = AmityPostRepository(client: client)
        
        if let communityId = communityId {
            repository.createPost(builder, targetId: communityId, targetType: .community)
                .subscribe { result in
                    print("Post with mentions created: \(result)")
                }
        }
    }
    
    // Validate mentions before creating post
    func validateAndCreatePost(
        text: String,
        mentionedUserIds: [String],
        completion: @escaping (Result<AmityPost, Error>) -> Void
    ) {
        // Validate users exist
        let userRepository = AmityUserRepository(client: client)
        
        let group = DispatchGroup()
        var validUserIds: [String] = []
        var errors: [Error] = []
        
        for userId in mentionedUserIds {
            group.enter()
            
            userRepository.getUser(withId: userId) { result in
                switch result {
                case .success:
                    validUserIds.append(userId)
                case .failure(let error):
                    errors.append(error)
                }
                group.leave()
            }
        }
        
        group.notify(queue: .main) {
            if !errors.isEmpty {
                completion(.failure(errors.first!))
                return
            }
            
            self.createTextPostWithMentions(
                text: text,
                mentionedUserIds: validUserIds,
                completion: completion
            )
        }
    }
}

extension String {
    func ranges(of substring: String) -> [Range<String.Index>] {
        var ranges: [Range<String.Index>] = []
        var startIndex = self.startIndex
        
        while startIndex < self.endIndex,
              let range = self.range(of: substring, range: startIndex..<self.endIndex) {
            ranges.append(range)
            startIndex = range.upperBound
        }
        
        return ranges
    }
}

​
Update Post with Mentions

Modify existing posts to add, remove, or update user mentions while maintaining post integrity.
The pattern for adding mentions to posts is consistent across all post types (text, image, video, file). The examples show text posts, but the same creation process applies to any post type.
  • iOS
  • Android
  • TypeScript
  • Flutter
// Update existing post with new mentions
func updatePostWithMentions(
    postId: String,
    newText: String,
    mentionedUserIds: [String],
    completion: @escaping (Result<AmityPost, Error>) -> Void
) {
    // Build updated mention metadata
    let mentionMetadata = buildMentionMetadata(text: newText, userIds: mentionedUserIds)
    
    let builder = AmityTextPostBuilder()
        .setText(newText)
        .setMentionUsers(mentionedUserIds)
        .setMetadata(mentionMetadata)
    
    let repository = AmityPostRepository(client: client)
    repository.editPost(withId: postId, builder: builder)
        .subscribe { result in
            completion(result)
        }
}

// Remove all mentions from a post
func removeMentionsFromPost(
    postId: String,
    newText: String,
    completion: @escaping (Result<AmityPost, Error>) -> Void
) {
    let builder = AmityTextPostBuilder()
        .setText(newText)
        .setMentionUsers([]) // Empty mention list
        .setMetadata([:])    // Empty metadata
    
    let repository = AmityPostRepository(client: client)
    repository.editPost(withId: postId, builder: builder)
        .subscribe { result in
            completion(result)
        }
}

​
Advanced Mention Features

  • User Existence: Verify mentioned users exist before creating posts
  • Permission Checks: Ensure users can be mentioned in the target context
  • Community Membership: Validate users are members of the target community
  • Privacy Settings: Respect user privacy preferences for mentions
  • Display Names: Store user display names for consistent rendering
  • Position Tracking: Maintain exact mention positions in text
  • Type Information: Support different mention types (users, groups, etc.)
  • Version Control: Track metadata format versions for compatibility
  • Auto-completion: Provide user suggestions as they type
  • Visual Highlighting: Style mentions differently from regular text
  • Click Handlers: Enable interaction with mentioned users
  • Accessibility: Support screen readers and keyboard navigation
  • Real-time Alerts: Notify mentioned users immediately
  • Batch Processing: Handle multiple mentions efficiently
  • Delivery Tracking: Monitor notification delivery status
  • User Preferences: Respect mention notification settings

​
Best Practices

Performance

Validate mentions before post creation and batch operations for efficiency

User Experience

Provide clear visual feedback for mentions and auto-completion features

Privacy

Respect user privacy settings and community mention policies

Accessibility

Ensure mentions work with screen readers and keyboard navigation

​
Render Mentions

For comprehensive mention rendering guidelines, including metadata structure, custom mention objects, and UI implementation patterns, refer to the Mentions Guide documentation.

​
Common Implementation Patterns

  • Auto-completion UI
  • Mention Parsing
class MentionInputViewController: UIViewController {
    @IBOutlet weak var textView: UITextView!
    private let mentionManager = PostMentionManager()
    
    func textView(_ textView: UITextView, shouldChangeTextIn range: NSRange, replacementText text: String) -> Bool {
        let currentText = textView.text as NSString
        let updatedText = currentText.replacingCharacters(in: range, with: text)
        
        // Check if user is typing a mention
        if text == "@" {
            showUserSuggestions()
        } else if updatedText.contains("@") {
            updateUserSuggestions(for: updatedText)
        }
        
        return true
    }
    
    private func showUserSuggestions() {
        // Show user picker or autocomplete list
    }
    
    private func updateUserSuggestions(for text: String) {
        let mentions = mentionManager.extractMentionsFromText(text)
        // Update suggestion list based on partial mentions
    }
}
Notification Behavior: When updating posts with mentions, the mentioned users will NOT receive new notifications. Mention notifications are only sent when posts are initially created.
Cross-Platform Consistency: The mention metadata structure is consistent across all platforms, enabling seamless mention rendering regardless of the client implementation.