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.
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.
For # to be treated as a channel reference in the message, you must first map a given # character to a specific channel. Without it, # will be treated as a regular string and will be shown as plain text.
You can implement channel referencing in your app similarly to user @mentions.
Requires App Context
To reference channels from a keyset, you must enable App Context for your app's keyset in the Admin Portal.
A sample implementation of channel referencing could include the following:
- Decide how many suggested channels you want to show after typing the required string (
#and at least three characters).
Get channel suggestions
GetChannelSuggestions() returns all suggested channels that match the provided 3-letter string from your app's keyset.
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
- Blueprint
- C++
Chat->GetChannelSuggestions(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 channel name you want to reference. |
Limit | int | Yes | 10 | Maximum number of returned channel names that match the typed 3-letter suggestion. The default value is set to 10, and the maximum is 100. |
Output
| Type | Description |
|---|---|
TArray<UPubnubChannel*> | Returned array of Channel objects. |
Basic usage
Return five channels that have names starting with Sup.
#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");
// Define the text to search for channel suggestions
FString SearchText = "Sup";
// Request channel suggestions with a limit of 5
TArray<UPubnubChannel*> ChannelSuggestions = Chat->GetChannelSuggestions(SearchText, 5);
Add referenced channel
For # to be treated as a channel reference in the message, you must first map a given # character to a specific channel. Use the SendText() method with an additional ReferencedChannels param to create this mapping. Without it, # will be treated as a regular string and will be shown as plain text.
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. |
→ ReferencedChannels | TMap<int, FPubnubReferencedChannel> | No | n/a | Object mapping the referenced channel (FString ID, FString Name) with the place where this reference (nameOccurrenceIndex) was mentioned in the message: export type MessageReferencedChannels = { [nameOccurrenceIndex: number]: { id: string; name: string } }. For example, { 0: { id: 123, name: "Support" }, 2: { id: 345, name: "Off-topic" } } means that Support will be shown on the first reference in the message and Off-topic on the third. |
Output
This method doesn't return any value.
Basic usage
Map #Support to the third # in the 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;
FPubnubReferencedChannel ReferencedChannel({"channel-1", "My Channel"});
TMap<int, FPubnubReferencedChannel> ReferencedChannels;
ReferencedChannels.Add(6, ReferencedChannel);
SendTextParams.ReferencedChannels = ReferencedChannels;
Get referenced channels
Use the ReferencedChannels() method to return all channel names referenced in a message.
Method signature
- Blueprint
- C++
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);