Create channels

Channel naming

Before creating channels, take the time to carefully plan your naming strategy. Stick to consistent naming conventions and structure your channels thoughtfully. This preparation helps you avoid increased complexity, performance bottlenecks, and scalability issues, ensuring your app remains manageable and efficient as it grows.

Create channels (Channel objects) of one of these types:

• Direct (1:1)
• Group
• Public

You can use PubNub's functionality via Blueprints or directly in C++ code.

• In Blueprints, the whole SDK is managed by a subsystem, so start by initalizing the PubnubChatSubsystem node. Afterwards, you can use the Pubnub Chat object reference.

Blueprint functions

The Blueprints provided in the documentation show how you can structure your application and may contain utility methods and elements like buttons that are not part of the Unreal Chat SDK and are meant to serve as guidance.

• In C++, you can use the PubNub SDK as any other Game Instance Subsystem.

  #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") // config optional

  Chat now allows you to call all Chat SDK functions, for example:

  Chat->DeleteUser("SomeUserID");

Usage in Blueprints and C++

Requires App Context

To store data about channels, you must enable App Context for your app's keyset in the Admin Portal.

No support for channel groups

Chat SDKs don't support channel groups. We recommend using a Core SDK to manage channel groups.

Create direct channel

Direct channels enable private 1:1 conversations. Use cases include personal conversations and professional collaboration.

CreateDirectConversation() performs these actions:

1. Creates a direct channel type
2. Sets channel membership for the channel owner
3. Invites the other user (generates an invite event)

If a conversation between the two users already exists, the method returns that existing channel.

Receive messages

Call Connect() to start receiving messages on the channel.

Method signature

Blueprint

C++ / Input parameters

1Chat->CreateDirectConversation(
2    UPubnubUser* User, 
3    FString ChannelID, 
4    FPubnubChatChannelData ChannelData, 
5    FPubnubChatMembershipData MembershipData = FPubnubChatMembershipData()
6);

* required

Parameter	Description
User * Type: UPubnubUser	User that you invite to join a channel.
ChannelID * Type: FString	ID of the direct channel. The channel ID is created automatically by a hashing function that takes the string of two user names joined by &, computes a numeric value based on the characters in that string, and adds the direct prefix in front. For example, direct.1234567890. You can override this default value by providing your own ID.
ChannelData * Type: FPubnubChatChannelData	Information about the channel.
FPubnubChatMembershipData Type: FPubnubChatMembershipData	The object containing all information about the user-channel membership. For more information, refer to FPubnubChatMembershipData.

FPubnubChatChannelData

* required

Parameter	Description
ChannelName Type: FString Default: n/a	Display name for the channel (must not be empty or consist only of whitespace characters).
Description Type: FString Default: n/a	Channel's identifier in an external system. You can use it to match id with a similar identifier from an external database.
CustomDataJson Type: FString Default: n/a	JSON providing custom data about the channel. Values must be scalar only; arrays or objects are not supported. Filtering App Context data through the custom property is not recommended in SDKs.
Status Type: FString Default: n/a	Tag that lets you categorize your app channels by their current state. The tag choice is entirely up to you and depends on your use case.
Type Type: FString Default: n/a	Tag that lets you categorize your app channels by their functional roles. The tag choice is entirely up to you and depends on your use case.

API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Output

Parameter	Description
FPubnubCreatedChannelWrapper Type: FPubnubCreatedChannelWrapper	Returned object containing these fields: CreatedChannel, HostMembership, and InviteesMemberships.
→ CreatedChannel Type: UPubnubChannel*	Returned object containing the updated channel metadata.
→ HostMembership Type: UPubnubMembership*	Returned object containing the updated host (channel owner) metadata.
→ InviteesMemberships Type: TArray<UPubnubMembership*>	Returned object containing the updated data of the invited users.

Sample code

Invite agent-007 to a 1:1 conversation to talk about customer XYZ.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

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

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

9// First, create a user object for agent-007
10FString UserID = "agent-007";
11FPubnubChatUserData UserData;
12UserData.UserName = "Agent 007";
13

14// Create the user
15UPubnubUser* InvitedUser = Chat->CreateUser(UserID, UserData);
16

17// Define the conversation/channel ID
18FString ChannelID = "direct.agent-007&my_user"; 
19

20// Define the channel data
21FPubnubChatChannelData ChannelData;
22ChannelData.ChannelName = "Conversation about customer XYZ";
23ChannelData.Description = "Discussion regarding customer XYZ";
24ChannelData.CustomDataJson = "{\"topic\": \"customer XYZ\"}";
25ChannelData.Status = "active";
26ChannelData.Type = "private";
27

28// Create the direct conversation
29FPubnubCreatedChannelWrapper CreatedChannelWrapper = Chat->CreateDirectConversation(InvitedUser, ChannelID, ChannelData);

show all 29 lines

Create group channel

Group channels enable multi-user conversations for team collaboration and community building. Access requires an invitation.

CreateGroupConversation() performs these actions:

1. Creates a group channel type
2. Sets channel membership for the channel owner
3. Invites other users to join

Receive messages

Call Connect() to start receiving messages on the channel.

Method signature

Blueprint

C++ / Input parameters

1Chat->CreateGroupConversation(
2    TArray<UPubnubUser*> Users, 
3    FString ChannelID, 
4    FPubnubChatChannelData ChannelData, 
5    FPubnubChatMembershipData MembershipData = FPubnubChatMembershipData()
6);

* required

Parameter	Description
Users * Type: TArray<UPubnubUser*>	Array of users that you invite to join a channel. You can invite a maximum number of 100 users at once.
ChannelID * Type: FString	ID of the group channel.
ChannelData * Type: FPubnubChatChannelData	Information about the channel. If you don't provide the name, the channel will get the same name as id.
MembershipData * Type: FPubnubChatMembershipData	The object containing all information about the user-channel membership. For more information, refer to FPubnubChatMembershipData.

Output

Parameter	Description
FPubnubCreatedChannelWrapper Type: FPubnubCreatedChannelWrapper	Returned object containing these fields: CreatedChannel, HostMembership, and InviteesMemberships.
→ CreatedChannel Type: UPubnubChannel*	Returned object containing the updated channel metadata.
→ HostMembership Type: UPubnubMembership*	Returned object containing the updated host (channel owner) metadata.
→ InviteesMemberships Type: TArray<UPubnubMembership*>	Returned object containing the updated data of the invited users.

Sample code

Create a group conversation and invite agent-007 and agent-008 to have weekly syncs on customer XYZ.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

4// Get the GameInstance and Chat subsystem
5UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(ContextObject);
6UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
7UPubnubChat* Chat = PubnubChatSubsystem->InitChat("demo", "demo", "my_user");
8

9// Create user objects for agent-007 and agent-008
10FString UserID_007 = "agent-007";
11FPubnubChatUserData UserData_007;
12UserData_007.UserName = "Agent 007";
13UPubnubUser* InvitedUser_007 = Chat->CreateUser(UserID_007, UserData_007);
14

15FString UserID_008 = "agent-008";
16FPubnubChatUserData UserData_008;
17UserData_008.UserName = "Agent 008";
18UPubnubUser* InvitedUser_008 = Chat->CreateUser(UserID_008, UserData_008);
19

20// Define the conversation/channel ID
21FString ChannelID = "group.agent-007&agent-008&my_user";
22

23// Define the channel data
24FPubnubChatChannelData ChannelData;
25ChannelData.ChannelName = "Weekly Sync on Customer XYZ";
26ChannelData.Description = "Weekly discussion regarding customer XYZ";
27ChannelData.CustomDataJson = "{\"topic\": \"customer XYZ\", \"frequency\": \"weekly\"}";
28ChannelData.Status = "active";
29ChannelData.Type = "group";
30

31FPubnubChatMembershipData MembershipData;
32MembershipData.CustomDataJson = "{\"role\": \"premium-support\"}";
33MembershipData.Status = "active";
34MembershipData.Type = "player";
35// Create the group conversation
36TArray<UPubnubUser*> Users = { InvitedUser_007, InvitedUser_008 };
37FPubnubCreatedChannelWrapper CreatedChannelWrapper = Chat->CreateGroupConversation(Users, ChannelID, ChannelData, MembershipData);

show all 37 lines

Create public channel

Public channels are open to anyone without invitation. Use cases include Q&A forums, knowledge sharing, and live event chat.

Supported features

Public channels do not support typing indicators or read receipts. These features are impractical for large audiences.

CreatePublicConversation() creates a public channel with the specified metadata.

Receive messages

Call Connect() to start receiving messages on the channel.

Method signature

Blueprint

C++ / Input parameters

1Chat->CreatePublicConversation(
2    FString ChannelID, 
3    FPubnubChatChannelData ChannelData
4);

* required

Parameter	Description
ChannelID * Type: FString	ID of the group channel.
ChannelData * Type: FPubnubChatChannelData	Information about the channel. If you don't provide the name, the channel will get the same name as id.

API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Output

Parameter	Description
Channel Type: UPubnubChannel*	Object returning the created channel metadata.

Sample code

Create a public ask-support channel.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

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

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

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

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

17// Create the conversation
18Chat->CreatePublicConversation(ChannelID, ChannelData);

show all 18 lines