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, you can access PubNub from any Widget or Actor. Start by initializing chat using InitChat on UPubnubChatSubsystem. Afterwards, you can use the returned UPubnubChat object reference to call all Chat SDK functions.

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 UPubnubChatSubsystem as any other Game Instance Subsystem.

  1
  

  Chat now allows you to call all Chat SDK functions, for example, Chat->GetChannel("my_channel").

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 channel with the direct type
2. Sets channel membership for the channel owner
3. Invites the other user and creates a membership with a "pending" status (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

C++ / Input parameters

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

* required

Parameter	Description
User * Type: UPubnubChatUser*	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. This function overwrites the value of the Type field and always sets it to "direct".
HostMembershipData 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	Detailed description of the channel's purpose or topic.
Custom 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. Maximum length is 50 characters.
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. Maximum length is 50 characters.

Blueprint

API limits

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

Output

Parameter	Description
FPubnubChatCreateDirectConversationResult Type: struct	Returned object containing these fields: Result, Channel, HostMembership, and InviteeMembership.
→ Result Type: FPubnubChatOperationResult	Operation result with Error (bool) and ErrorMessage (FString).
→ Channel Type: UPubnubChatChannel*	Returned object containing the created channel metadata.
→ HostMembership Type: UPubnubChatMembership*	Returned object containing the host (channel owner) membership.
→ InviteeMembership Type: UPubnubChatMembership*	Returned object containing the invited user's membership.

Sample code

Reference code

This example is a self-contained code snippet ready to be run. Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code. Use it as a reference when working with other examples in this document.

Create a direct conversation with another user asynchronously.

Actor.h

1

Actor.cpp

1

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 channel with the group type
2. Sets channel membership for the channel owner
3. Invites other users to join and creates memberships with a "pending" status

Receive messages

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

Method signature

C++ / Input parameters

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

* required

Parameter	Description
Users * Type: TArray<UPubnubChatUser*>	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. This function overwrites the value of the Type field and always sets it to "group".
HostMembershipData Type: FPubnubChatMembershipData	The object containing all information about the user-channel membership. For more information, refer to FPubnubChatMembershipData.

Blueprint

Output

Parameter	Description
FPubnubChatCreateGroupConversationResult Type: struct	Returned object containing these fields: Result, Channel, HostMembership, and InviteesMemberships.
→ Result Type: FPubnubChatOperationResult	Operation result with Error (bool) and ErrorMessage (FString).
→ Channel Type: UPubnubChatChannel*	Returned object containing the created channel metadata.
→ HostMembership Type: UPubnubChatMembership*	Returned object containing the host (channel owner) membership.
→ InviteesMemberships Type: TArray<UPubnubChatMembership*>	Returned object containing the invited users' memberships.

Sample code

Reference code

This example is a self-contained code snippet ready to be run. Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code. Use it as a reference when working with other examples in this document.

Create a group conversation and invite users to join asynchronously.

Actor.h

1

Actor.cpp

1

Other examples

Create group conversation with custom data

Actor.h

1

Actor.cpp

1

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 channel with the public type and the specified metadata.

Receive messages

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

Method signature

C++ / Input parameters

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

* required

Parameter	Description
ChannelID Type: FString	ID of the public channel.
ChannelData Type: FPubnubChatChannelData	Information about the channel. If you don't provide the name, the channel will get the same name as id. This function overwrites the value of the Type field and always sets it to "public".

Blueprint

API limits

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

Output

Parameter	Description
FPubnubChatChannelResult Type: struct	Returned object containing Result (FPubnubChatOperationResult) and Channel (UPubnubChatChannel*).

Sample code

Reference code

This example is a self-contained code snippet ready to be run. Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code. Use it as a reference when working with other examples in this document.

Create a public channel asynchronously.

Actor.h

1

Actor.cpp

1

Other examples

Create public conversation with custom data

Actor.h

1

Actor.cpp

1