Reference channels

Channel referencing lets users mention specific channel names in a chat conversation. They can do it by adding # and typing at least three first letters of the channel name they want to reference. As a result, they get a list of suggested names when typing such a suggestion, like #Sup.

Generic referencing

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

Usage in Blueprints and C++

The list of returned channels contains all channels in an app (channel data taken from the Admin Portal keyset for the app), regardless of whether the users are members of these channels. The number of returned suggested channels for reference also depends on the app configuration and can show up to 100 suggestions. The names of the suggested channels can consist of multiple words.

You can configure your app to let users refer up to 100 channels in a single message (default value is 10) and show references as links.

You can implement channel referencing in your app similarly to user mentions and links.

Requires App Context

To reference channels from a keyset, you must have App Context enabled for your app's keyset in the Admin Portal.

Add channel references

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

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

Method signature

You can add a channel reference by calling the AddMention() method with the MentionTarget of type Channel.

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 #offtopic is a channel reference (channel name is offtopic).

// 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 channel mention target for #offtopic
FString ChannelName = "offtopic";
UPubnubMentionTarget* ChannelMentionTarget = UPubnubMentionTarget::CreateChannelMentionTarget(ChannelName);

// Add the channel mention for #offtopic - '#offtopic' is mention of 'offtopic' channel
MyMessageDraft->AddMention(45, ChannelName.Len() +1, ChannelMentionTarget); 
// 45 is Possition of # in the text.
// ChannelName.Len() +1 because we add # to the reference

show all 17 lines

Remove channel references

RemoveMention() lets you remove a previously added channel reference from a draft message.

Method signature

You can remove a channel reference from a draft message by calling the RemoveMention() method at the exact offset where the reference 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 channel reference from the Hello Alex! I have sent you this link on the #offtopic channel. message where #offtopic is a channel reference.

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

Get channel 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 channels referenced 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 referenced channel whenever the draft is updated and channels 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 channel reference
    for (const FPubnubSuggestedMention& Suggestion : SuggestedMentions)
    {
        // Check if the suggestion corresponds to a channel reference

show all 32 lines

Get referenced channels

Use the ReferencedChannels() method to return all channel names referenced in a message.

Method signature

Blueprint

C++ / Input parameters

Message->ReferencedChannels();

Output

Type	Description
TArray<FPubnubReferencedChannel>	Returned array of referenced channel (FString ID, FString Name) objects.

Basic usage

Check if a message on the support channel contains any channel references.

#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");

FString Timetoken = "17228457425416757";

// Fetch the message
UPubnubMessage* Message = Channel->GetMessage(Timetoken);

show all 16 lines