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 types.

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

Enable App Context in the Admin Portal to mention users.

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

Remove user mentions

RemoveMention() lets you remove a previously added 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

If you don't provide the position of the first character of the message element to remove, it isn't 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

Get user suggestions

The event handler you attached to the OnDraftUpdated event returns all users referenced in the draft message that match the provided 3-letter string from your app's keyset.

The event handler returns suggestions for channel references, user mentions, and links using <List<MessageElement> and <List<SuggestedMention>.

• <List<MessageElement> represent the draft's current state and can include plain text or links, such as user mentions, channel references, or URLs. These elements are organized to reflect their order in the draft.
• <List<SuggestedMention> provides potential mentions when available.

Single listener

For example, if you type Sam, you will get the list of users starting with Sam like Samantha or Samir. The default number of returned suggested usernames is 10 which is configurable to a maximum value of 100.

Method signature

You must handle the event to update to the contents of a message draft, as well as retrieve the current message elements suggestions for user mentions, channel reference, and links. For example, when the message draft contains ... @name ... or ... #chann ....

Enable receiving suggested mentions

You must enable receiving suggested mentions by setting messageDraft.ShouldSearchForSuggestions = true; before introducing your event handler.

Refer to the Add a message draft listener section for details.

Sample code

Insert the first suggested mention whenever the draft is updated and mentions are detected.

1

Get mentioned users

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

Properties

Property	Description
MentionedUsers Type: List<User>	List of all users mentioned in a message.

Sample code

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

1

Collect all user-related mentions

The GetCurrentUserMentions() method lets you collect in one place all instances when a specific user was mentioned by someone — either in channels or threads. You can use this info to create a channel with all user-related mentions.

Method signature

This method has the following signature:

1chat.GetCurrentUserMentions(string startTimeToken, string endTimeToken, int count)

Input

* required

Parameter	Description
startTimetoken * Type: string Default: n/a	Timetoken delimiting the start of a time slice (exclusive) to pull messages with mentions from. For details, refer to the Fetch History section.
endTimetoken * Type: string Default: n/a	Timetoken delimiting the end of a time slice (inclusive) to pull messages with mentions from. For details, refer to the Fetch 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 Unity SDK docs.

Output

This method returns an awaitable Task<UserMentionsWrapper> with the wrapper object containing two fields: Mentions and IsMore.

Parameter	Description
Mentions Type: List<UserMentionData>	Array listing the requested number of historical mention events with a set of information that differ slightly depending on whether you were mentioned in the main (parent) channel or in a thread. For mentions in the parent channel, the returned UserMentionData includes these fields: ChannelId where you were mentioned, userId that mentioned you, Event (of type Mention), Message that included the mention. For mentions in threads, the returned UserMentionData includes similar fields, the only difference is that you'll get ParentChannelId and ThreadChannelId fields instead of just ChannelId to clearly differentiate the thread that included the mention from the parent channel in which this thread was created.
IsMore Type: bool	Info whether there are more historical events to pull.

Sample code

List the last ten mentions for the current chat user.

1

Show notifications for mentions

You can monitor all events emitted when you are mentioned in a parent or thread channel you are a member of.

Use the StreamMentionEvents() method to enable or disable mention event streaming on a user, and the OnMentionEvent event to handle mention updates. You can use this to create pop-up notifications for the users.

Events documentation

To read more about the events of type Mention, refer to the Chat events documentation.

Method naming

Earlier versions used SetListeningForMentionEvents() to enable streaming. This method has been superseded by StreamMentionEvents(), though it remains available for backward compatibility.

Method signature

These methods take the following parameters:

• StreamMentionEvents()

  1user.StreamMentionEvents(bool stream)

• OnMentionEvent - Event signature

  1// event on the User entity
  2public event Action<ChatEvent> OnMentionEvent;
  3// needs a corresponding event handler
  4void EventHandler(ChatEvent mentionEvent)

Input

Parameter	Required in StreamMentionEvents()	Required in OnMentionEvent	Description
stream Type: bool Default: n/a	Yes	n/a	Whether to start (true) or stop (false) listening to mention events for the user.
mentionEvent Type: ChatEvent Default: n/a	No	Yes	The mention event containing information about the mention.

Output

These methods don't return a value. Mention event updates are delivered through the OnMentionEvent event handler.

Sample code

Print a notification for a mention of the current chat user on the support channel.

1