Mention users

Tag users in chat messages with @ mentions. Type @ followed by at least three letters to see username suggestions.

Generic referencing

Channel references, user mentions, and links are MessageElement instances with different MentionTarget values.

Configuration options:

• User source: channel members or all app users
• Suggestions: up to 100 usernames (default: 10)
• Username length: up to 200 characters
• Mentions per message: up to 100 (default: 10)

Implementation follows similar patterns to channel referencing and links.

Requires App Context

To mention users from a keyset, you must enable App Context for your app's keyset in the Admin Portal.

Add user mentions

Add user mentions with @ followed by at least three letters (e.g., @Mar).

Mentioned users are stored in the MessageDraft object. When sent with send(), mention data is saved to message metadata.

Method signature

You can add a user reference by calling the addMention() method with the target of MentionTarget.User.

Refer to the addMention() method for details.

Sample code

Create the Hello Alex! I have sent you this link on the #offtopic channel. message where Alex is a user mention.

1// create an empty message draft
2val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)
3

4// change the text
5messageDraft.update(text = "Hello Alex! I have sent you this link on the #offtopic channel.")
6

7// add a user mention to the string 'Alex'
8messageDraft.addMention(offset = 6, length = 4, target = MentionTarget.User(userId = "alex_d"))

Remove user mentions

removeMention() removes a user mention from a draft message.

Method signature

You can remove user mentions from a draft message by calling the removeMention() method at the exact offset where the user mention starts.

Refer to the removeMention() method for details.

Offset value

Provide the exact offset position where the mention starts; otherwise, it won't be removed.

Sample code

Remove the user mention from the Hello Alex! I have sent you this link on the #offtopic channel. message where Alex is a user mention.

1// assume the message reads
2// Hello Alex! I have sent you this link on the #offtopic channel.`
3

4// remove the channel reference
5messageDraft.removeMention(offset = 6)

Get user suggestions

getUserSuggestions() returns users matching a 3-letter string from channel members or global users.

Example: typing Sam returns Samantha, Samir, etc. Default limit: 10 users (max: 100).

Method signature

You must add a message elements listener to receive user suggestions.

Refer to the addChangeListener() method for details.

Sample code

1// create a message draft
2val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)
3

4// add the listener
5val listener = { elements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>> ->
6        updateUI(elements) // updateUI is your own function for updating UI
7        suggestedMentions.async { result ->
8            result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions
9        }
10    }
11messageDraft.addChangeListener(listener)

Get mentioned users

To return all users mentioned in a message, use the getMessageElements() method.

Method signature

This method has the following signature:

1message.getMessageElements(): List<MessageElement>

Input

This method doesn't take any parameters.

Output

Type	Description
List<MessageElement>	A list of message elements representing parsed components of the input text, including processed user mentions, links, and referenced channels based on the available data.

Each MessageElement on the returned list can be of one of these types:

• data class PlainText(override val text: String) : MessageElement
• data class Link(override val text: String, val target: MentionTarget) : MessageElement

If a MessageElement is of type Link, its target depends on the returned item:

// Mentioned user identified by [userId].
data class User(val userId: String) : MentionTarget


// Referenced channel identified by [channelId].
data class Channel(val channelId: String) : MentionTarget


// Link to [url].
data class Url(val url: String) : MentionTarget

MessageElement details

Sample code

Check if the message with the 16200000000000000 timetoken contains any mentions.

1chat.getChannel("incident-management").async { channelResult ->
2    channelResult.onSuccess { channel ->
3        // Successfully retrieved the channel
4        channel?.getMessage(16200000000000000L)?.async { messageResult ->
5            messageResult.onSuccess { message ->
6                // Handle success
7                val elements = message?.getMessageElements()
8

9                // Check if any elements represent user mentions
10                val hasMentions = elements?.any { element ->
11                    // Assuming there's a specific type or condition for mentions
12                    element is Link && element.target is User
13                } ?: false
14

15                if (hasMentions) {
16                    println("The message contains mentions.")
17                } else {
18                    println("The message does not contain any mentions.")
19                }
20            }.onFailure { error ->
21                // Handle failure
22                println("Failed to retrieve the message: ${error.message}")
23            }
24        }
25    }.onFailure { error ->
26        // Failed to retrieve the channel
27        println("Failed to retrieve the channel: ${error.message}")
28    }
29}

show all 29 lines

Collect all user-related mentions

getCurrentUserMentions() retrieves all instances where the current user was mentioned in channels or threads. Use this to build a mentions feed.

Method signature

This method has the following signature:

1chat.getCurrentUserMentions(
2    startTimetoken: Long?,
3    endTimetoken: Long?,
4    count: Int = 100
5): PNFuture<GetCurrentUserMentionsResult>

Input

* required

Parameter	Description
startTimetoken Type: Long Default: n/a	Timetoken delimiting the start of a time slice (exclusive) to pull messages with mentions from. For details, refer to the Batch History section.
endTimetoken Type: Long Default: n/a	Timetoken delimiting the end of a time slice (inclusive) to pull messages with mentions from. For details, refer to the Batch History section.
count Type: Int Default: 100	Number of historical messages with mentions to return in a single call. Since each call returns all attached message actions by default, the maximum number of returned messages is 100. For more details, refer to the description of the includeMessageActions parameter in the Kotlin SDK docs. The default value is 100.

Output

Parameter	Description
PNFuture<GetCurrentUserMentionsResult> Type: object	Returned object containing two fields: mentions and isMore.
→ mentions Type: List<UserMention>	List of mention events. Each UserMention contains: message (the Message object), userId (who triggered the mention), channelId (where the mention occurred), and parentChannelId (the parent channel if the mention is in a thread, otherwise null).
→ isMore Type: Boolean	Info whether there are more historical events to pull.

Sample code

List the last ten mentions for the current chat user.

1chat.getCurrentUserMentions(count = 10).async { mentionsResult ->
2    mentionsResult.onSuccess { mentions ->
3        // handle success
4        println("Last 10 mentions for the current user:")
5        mentions.mentions.forEach { mention ->
6            println("Message: ${mention.message.text}, Mentioned At: ${mention.message.timetoken}")
7        }
8    }.onFailure { exception ->
9        // handle failure
10        println("Error getting user mentions")
11    }
12}

Show notifications for mentions

onMentioned() monitors mention events on the User object. Use this to trigger pop-up notifications when the current user is mentioned in a channel or thread.

Deprecated method

listenForEvents<EventContent.Mention>() is deprecated. Use user.onMentioned() instead, which provides a typed Mention object.

Method signature

This method has the following parameters:

1user.onMentioned(callback: (mention: Mention) -> Unit): AutoCloseable

Input

* required

Parameter	Description
callback * Type: (mention: Mention) -> Unit Default: n/a	Function invoked with a Mention event whenever the user is mentioned.

The Mention object contains:

Property	Description
messageTimetoken Type: Long	The timetoken of the message containing the mention.
channelId Type: String	The channel where the mention occurred.
parentChannelId Type: String?	The parent channel if the mention is in a thread, otherwise null.
mentionedByUserId Type: String	The user ID of the message author who created the mention.

Output

Type	Description
AutoCloseable	Interface that lets you stop receiving mention events by invoking the close() method.

Sample code

Print a notification when the current user is mentioned.

1val user = chat.currentUser
2

3val subscription = user.onMentioned { mention ->
4    println("Mentioned in channel ${mention.channelId} at timetoken ${mention.messageTimetoken} by ${mention.mentionedByUserId}")
5}
6

7// stop listening:
8// subscription.close()

Get mentioned users (deprecated)

You can access the mentionedUsers property of the Message object to return all users mentioned in a message.

Method signature

This is how you can access the property:

1message.mentionedUsers

Sample code

Check if the message with the 16200000000000000 timetoken contains any mentions.

1channel.getMessage(16200000000000000).async { result ->
2    result.onSuccess { message: Message? ->
3        if (message != null) {
4            // Access the mentionedUsers property
5            val mentionedUsers = message.mentionedUsers
6            
7            if (mentionedUsers != null && mentionedUsers.isNotEmpty()) {
8                println("The message contains the following mentioned users:")
9                mentionedUsers?.forEach { (index, user) ->
10                    println("User: ${user.name}")
11                }
12            } else {
13                println("The message does not contain any mentions.")
14            }
15        } else {
16            println("Message does not exist")
17        }
18    }.onFailure { exception: PubNubException ->
19        println("Exception occurred: ${exception.message}")
20    }
21}

show all 21 lines