Mention users

The Mentions feature lets users tag specific individuals within a chat or conversation.

Usage in Blueprints and C++

Unreal 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) and configure mentions to be shown as links or display user details when highlighted (for example, by hovering over them).

For @ to be treated as a mention in the message, you must first map a given @ character to a specific user. Without it, @ will be treated as a regular string and will be shown as plain text.

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.

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

Blueprint
C++

Chat->GetUserSuggestions()

Chat->GetUserSuggestions(
  FString Text, 
  int Limit = 10
);

Channel->GetUserSuggestions()

Channel->GetUserSuggestions(
  FString Text, 
  int Limit = 10
);

Parameter	Type	Required	Default	Description
`Text`	`FString`	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
`TArray<UPubnubMembership*>`	Yes	No	Returned array of `Membership` objects.
`TArray<UPubnubUser*>`	No	Yes	Returned array of `User` objects.

Basic usage

Return five channel users whose names start with Mar.

#include "Kismet/GameplayStatics.h"
#include "PubnubChatSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();

UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");

FString Text = "Mar";

Chat->GetUserSuggestions(Text);

Send message with mentions

SendText() publishes the text message with mentioned users and emits events of type mention.

Use the SendText() method with an additional MentionedUsers param to send a message with user mentions.

Method signature

Blueprint
C++

Channel->SendText(
    FString Message, 
    FSendTextParams SendTextParams = FSendTextParams()
);

Parameter	Type	Required	Default	Description
`Message`	`FString`	No	n/a	Text that you want to send to the selected channel.
`SendTextParams`	`FSendTextParams`	No	n/a	Struct providing additional parameters.
→ `MentionedUsers`	`TMap<int, FPubnubMentionedUser>`	No	n/a	Object mapping a mentioned user (`FString ID`, `FString Name`) with the number of mention (`nameOccurrenceIndex`) in the message: `export type MessageMentionedUsers = { [nameOccurrenceIndex: number]: { id: string; name: string } }`. For example, `{ 0: { id: 123, name: "Mark" }, 2: { id: 345, name: "Rob" } }` means that `Mark` will be shown on the first mention in the message and `Rob` on the third.

Basic usage

Mention the users @James, Sarah and @Twain, Mark in a message.

#include "Kismet/GameplayStatics.h"
#include "PubnubChatSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();

UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");

UPubnubChannel* Channel = Chat->GetChannel("support");
FSendTextParams SendTextParams;

FSendTextParams SendTextParams;
FPubnubMentionedUser MentionedUser({"twain_mark", "Twain, Mark"});
FPubnubMentionedUser MentionedUser2({"james_sarah", "James, Sarah"});
TMap<int, FPubnubMentionedUser> MentionedUsers;
show all 20 lines

Get mentioned users

Use the MentionedUsers() method to return all users mentioned in a message.

Method signature

Blueprint
C++

Message->MentionedUsers()

Output

Type	Description
`TArray<FPubnubMentionedUser>`	Array with specific mentioned users.

FPubnubMentionedUser

Property	Type	Description
`Id`	`FString`	Unique identifier of the mentioned user.
`Name`	`FString`	Name of the mentioned user.

Basic usage

Check if the last message on the support channel contains any mentions.

#include "Kismet/GameplayStatics.h"
#include "PubnubChatSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();

UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");

UPubnubChannel* Channel = Chat->GetChannel("support");

// Fetch historical messages
TArray<UPubnubMessage*> Messages = Channel->GetHistory();

UPubnubMessage* Message = Messages.Messages[0];

show all 16 lines

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

Blueprint
C++

Chat->GetCurrentUserMentions(FString StartTimetoken, FString EndTimetoken, int Count)

Parameter	Type	Required	Default	Description
`StartTimetoken`	`FString`	No	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`	`FString`	No	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`	No	`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 Unreal SDK docs.

Output

This method returns a FPubnubUserMentionDataList object containing two fields: UserMentions and IsMore.

Parameter	Type	Description
`UserMentions`	`TArray<FPubnubUserMentionData>`	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 information includes these fields: `ChannelID` where you were mentioned, `UserID` that mentioned you, `Event` (of type `mention`), and `Message` that included the mention. For mentions in threads, the returned information 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.

#include "PubnubChatSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(ContextObject);
UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();

UPubnubChat* Chat = PubnubChatSubsystem->InitChat("demo", "demo", "my_user");

// Define the conversation/channel ID
FString ChannelID = "ask-support"; 

// Define the channel data
FPubnubChatChannelData ChannelData;
ChannelData.ChannelName = "ask-support";
ChannelData.Description = "Space dedicated to answering all support-related questions";

show all 31 lines

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 ListenForEvents() 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

Blueprint
C++

Chat->ListenForEvents(
    FString ChannelID, 
    EPubnubChatEventType ChatEventType, 
    FOnPubnubEventReceived EventCallback
);

Parameter	Type	Required	Default	Description
`ChannelID`	`FString`	Yes	`user.id`	Channel to listen for new `mention` events. In the case of `mention` events, this channel is always the current user's ID.
`ChatEventType`	`EPubnubChatEventType`	No	n/a	Type of events. `PCET_MENTION` is the type defined for all mention events
`EventCallback`	`FOnPubnubEventReceived`	Yes	n/a	Callback function passed as a parameter. It defines the custom behavior to be executed whenever an `mention` event type is detected on the specified channel.

EPubnubChatEventType

Value	Description
`PCET_TYPING`	Indicates a user is typing a message. Displayed as Typing.
`PCET_REPORT`	Represents an event where a message has been flagged or reported for offensive content. Displayed as Report.
`PCET_RECEIPT`	Confirms receipt of a message or event. Displayed as Receipt.
`PCET_MENTION`	Indicates that a user has been mentioned in a message. Displayed as Mention.
`PCET_INVITE`	Represents an invitation event typically sent to a specific user. Displayed as Invite.
`PCET_CUSTOM`	Custom event type for specialized behavior or use cases. Displayed as Custom.
`PCET_MODERATION`	Represents an event related to content moderation actions. Displayed as Moderation.

Handle the response

Output

Type	Description
`UPubnubCallbackStop*`	Object on which you can call `Stop()` to stop receiving updates.

Basic usage

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

#include "Kismet/GameplayStatics.h"
#include "PubnubChatSubsystem.h"

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();

UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");

UPubnubChannel* Channel = Chat->GetChannel("support");

FSendTextParams SendTextParams;
FPubnubMentionedUser MentionedUser({"admin_george", "Administrator"});
TMap<int, FPubnubMentionedUser> MentionedUsers;
MentionedUsers.Add(1, MentionedUser);
SendTextParams.MentionedUsers = MentionedUsers;
show all 28 lines

Usage in Blueprints and C++

Requires App Context

Get user suggestions​

Method signature​

Output​

Basic usage​

Send message with mentions​

Method signature​

Basic usage​

Get mentioned users​

Method signature​

Output​

FPubnubMentionedUser​

Basic usage​

Collect all user-related mentions​

Method signature​

Output​

Basic usage​

Show notifications for mentions​

Events documentation

Method signature​

EPubnubChatEventType​

Handle the response

Output​

Basic usage​

Get user suggestions

Method signature

Output

Basic usage

Send message with mentions

Method signature

Basic usage

Get mentioned users

Method signature

Output

FPubnubMentionedUser

Basic usage

Collect all user-related mentions

Method signature

Output

Basic usage

Show notifications for mentions

Method signature

EPubnubChatEventType

Output

Basic usage