Mention users
The Mentions feature lets users tag specific individuals within a chat or conversation.
Unity Chat SDK lets one user tag another user by adding @
and typing at least three first letters of the username they want to mention. As a result, they get a list of suggested usernames when typing such a suggestion, like @Mar
.
The list of returned users depends on your app configuration - these can be either all members in the channel where you write a message or all users of your app (user data taken from the Admin Portal keyset for your app). The number of returned suggested users for the mention also depends on your app configuration and can show up to 100
suggestions. The names of the suggested users can consist of multiple words and contain up to 200 characters.
You can configure your app to let users mention up to 100
users in a single message (default value is 10
).
You can implement mentions in your app in a similar way you would implement channel referencing.
Requires App Context
To mention users from a keyset, you must enable App Context for your app's keyset in the Admin Portal.
Send message with user mentions
You can let users mention other users in a message by adding @
and typing at least three first letters of the username they want to mention, like @Mar
.
Method signature
Head over to the SendText()
method for details.
Basic usage
Mention Samantha
and Samir
(@Sam
) in a message.
if(!chat.TryGetUser("Samantha", out var userSamantha) || !chat.TryGetUser("Samir", out var userSamir))
{
return;
}
channel.SendText("Hi @Samantha and @Samir!", new SendTextParams()
{
MentionedUsers = new Dictionary<int, User>() {
{ 0, userSamantha },
{ 1, userSamir },
}
});
Get user suggestions
GetUserSuggestions()
returns all suggested users that match the provided 3-letter string from a selected data source (channel members or global users on your app's keyset).
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
This method can be called on two Unity Chat SDK objects and has the following signature:
-
Called on the
Channel
objectchannel.GetUserSuggestions(
string text,
int limit = 10
) -
Called on the
Chat
objectchat.GetUserSuggestions(
string text,
int limit = 10
)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
text | string | Yes | n/a | At least a 3-letter string typed in after @ with the user name you want to mention. |
limit | int | Yes | 10 | Maximum number of returned usernames that match the typed 3-letter suggestion. The default value is set to 10 , and the maximum is 100 . |
Output
Type | Returned on Channel object | Returned on Chat object | Description |
---|---|---|---|
List<Membership> | Yes | No | Returned list of Membership objects. |
List<User> | No | Yes | Returned list of User objects. |
Basic usage
Return five channel users whose names start with Mar
.
-
Called on the
Channel
object
show all 19 lines// try to get the "support" channel
if (chat.TryGetChannel("support", out Channel channel))
{
Console.WriteLine($"Found channel with name {channel.Name}");
// get user suggestions with names starting with "Mar" and limit to 5 results
var userSuggestions = channel.GetUserSuggestions("@Mar", limit: 5);
// print out the suggested user names
Console.WriteLine("User suggestions:");
foreach (User user in userSuggestions)
{
Console.WriteLine(user.UserName);
}
} -
Called on the
Chat
object
show all 19 lines// try to get the "support" channel
if (chat.TryGetChannel("support", out Channel channel))
{
Console.WriteLine($"Found channel with name {channel.Name}");
// get user suggestions from the chat object with names starting with "Mar" and limit to 5 results
var userSuggestions = chat.GetUserSuggestions("@Mar", limit: 5);
// print out the suggested user names
Console.WriteLine("User suggestions:");
foreach (User user in userSuggestions)
{
Console.WriteLine(user.UserName);
}
}
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:
message.MentionedUsers
Properties
Property | Type | Description |
---|---|---|
MentionedUsers | List<User> | List of all users mentioned in a message. |
Basic usage
Check if the message with the 16200000000000000
timetoken contains any mentions.
// reference the "support" channel
if (chat.TryGetChannel("support", out var channel))
{
Console.WriteLine($"Found channel with name {channel.Name}");
// get the message with the specified timetoken
if (channel.TryGetMessage("16200000000000000", out var message))
{
Console.WriteLine($"Message: {message.MessageText}");
// check if the message contains any mentions
if (message.MentionedUsers != null && message.MentionedUsers.Count > 0)
{
Console.WriteLine("The message contains mentions.");
foreach (var mentionedUser in message.MentionedUsers)
show all 33 linesCollect 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:
chat.GetCurrentUserMentions(string startTimeToken, string endTimeToken, int count)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
startTimetoken | string | Yes | 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 | string | Yes | 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 | int | Yes | 100 | Number of historical messages with mentions to return in a single call. Since each call returns all attached message reactions 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 object containing two fields: Mentions
and IsMore
.
Parameter | Type | Description |
---|---|---|
Mentions | 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 | bool | Info whether there are more historical events to pull. |
Basic usage
List the last ten mentions for the current chat user.
// fetch the last 10 mentions for the current user
var mentions = chat.GetCurrentUserMentions(string.Empty, string.Empty, 10);
if (mentions != null && mentions.Mentions.Any())
{
foreach (var mention in mentions.Mentions)
{
Console.WriteLine($"Mentioned in Channel ID: {mention.ChannelId}, Message: {mention.Message.MessageText}");
}
}
else
{
Console.WriteLine("No mentions found.");
}
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 using the StartListeningForMentionEvents()
method. You can use this method 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 signature
This method has the following parameters:
// start listening
chat.StartListeningForMentionEvents(string userId)
// triggered mention event
public event Action<MentionEvent> OnMentionEvent;
// needs a corresponding event handler
void EventHandler(MentionEvent event)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
userId | string | Yes | Channel equal to user ID | Channel to listen for new Mention events. In the case of Mention events, this channel is always the current user's ID. |
Output
This method doesn't return any data.
Basic usage
Print a notification for a mention of the current chat user on the support
channel.
if(!chat.TryGetCurrentUser(out var user))
{
return;
}
chat.StartListeningForMentionEvents(user.Id);
chat.OnMentionEvent += mentionEvent =>
{
if(mentionEvent.ChannelId == "support")
{
Console.WriteLine($"{user.Id} has been mentioned on the support channel!");
}
};