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.

Generic referencing

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

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

AddMention() lets you replace a plain user on the draft message to display a meaningful mention in the published message.

You can use the static CreateUserMentionTarget() method to create a mention target that links to a specified User and reference it in the method.

Method signature

You can add a user mention by calling the AddMention() method with the MentionTarget of type User.

Refer to the AddMention() method for details.

Basic usage

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

// Create a message draft
UPubnubMessageDraft* MyMessageDraft = Channel->CreateMessageDraft();

// Insert the whole text to the message draft
MyMessageDraft->InsertText(0, "Hello Alex! I have sent you this link on the #offtopic channel.");

// Create a user mention target for Alex
FString UserName = "Alex";
UPubnubMentionTarget* UserMentionTarget = UPubnubMentionTarget::CreateUserMentionTarget(UserName);

// Add the user mention for Alex
MyMessageDraft->AddMention(6, UserName.Len(), UserMentionTarget); // 'Hello ' is 6 characters long

// Send the message draft with the user mention
MyMessageDraft->Send();

Remove user mentions

RemoveMention() lets you remove a previously added user mention from a draft message.

Method signature

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

Refer to the RemoveMention() method for details.

Position value

If you don't provide the position of the first character of the message element to remove, it isn't removed.

Basic usage

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.

// Assume the message reads
// Hello Alex! I have sent you this link on the #offtopic channel.`
// Remove the user reference
MessageDraft->RemoveMention(6)

Get user suggestions

Add a callback to listen for changes to the message draft along with receiving suggestions for user mentions, links, and channel references.

AddChangeListenerWithSuggestions() returns all users mentioned in the draft message that match the provided 3-letter string from your app's keyset.

Single listener

For example, if you type #Sup, you will get the list of channels starting with Sup like Support or Support-Agents. The default number of returned suggested channel names is 10, configurable to a maximum value of 100.

Method signature

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

Basic usage

Insert the first mentioned user whenever the draft is updated and users are detected.

// Assuming you have a UPubnubMessageDraft pointer named MyMessageDraft

// Define your callback function to handle updates with suggestions
void AMyActor::OnMessageDraftUpdateWithSuggestions(const TArray<UPubnubMessageElement*>& MessageElements, const TArray<FPubnubSuggestedMention>& SuggestedMentions)
{
    // Check if there are any suggested mentions
    if (SuggestedMentions.Num() == 0)
    {
        return;
    }

    // Iterate over suggested mentions to find a user reference
    for (const FPubnubSuggestedMention& Suggestion : SuggestedMentions)
    {
        // Check if the suggestion corresponds to a user reference

show all 32 lines

Get mentioned users

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

Method signature

Blueprint

C++ / Input parameters

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

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

Blueprint

C++ / Input parameters

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++ / Input parameters

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