Initial configuration

Initialize and configure the Unreal Chat SDK before building your chat app.

Prerequisites

1. Sign in or create an account on the Admin Portal.
2. Create an app to get your Publish Key and Subscribe Key.

Limit of 3 keysets for Free tier accounts

Effective February 3, 2025, all Free tier accounts are limited to a maximum of three keysets. If your account exceeds this limit, you must delete existing keysets to create new ones.

A new app receives demo keys automatically. You can create multiple keysets per app. Use separate keysets for production and test environments.

Required keyset settings

Enable these features on your keyset in the Admin Portal:

• App Context - Store user and channel data
• Presence - Track online/offline status
• Message Persistence - Store message history

Configure Unreal Engine

1. Download and install Unreal Engine version 5.0 or higher.
2. Create a new blank C++ Unreal project in a location of your choice.
3. Create an empty Plugins folder in your Unreal project's location.

Blueprint project package bug

If you create a Blueprint project, you may encounter a bug when packaging your app. Refer to Package a Blueprint project for more information.

Download the SDK

Required dependency

The PubNub Unreal Engine Chat SDK is not a standalone plugin. It requires the PubNub Unreal Engine SDK to be present in your project's Plugins folder. Both must be installed together.

In the Plugins folder of your Unreal project:

1. Clone the content of the Unreal SDK and the Unreal Engine Chat repositories.

2. Rename the cloned folders to Pubnub and PubnubChatSDK respectively.

Configure the workspace

1. In the project's root folder, right-click the projectname.uproject file and select the appropriate option for your operating system:

   OS	Selection
   MacOS	Services -> Generate xCode project
   Windows	Generate Visual Studio project files

2. Open the generated workspace for your OS.

3. Navigate to Source/_{YourProject}_/_{YourProject}_.Build.cs and add a dependency to PubnubChatSDK.

   PrivateDependencyModuleNames.AddRange(new string[] { "PubnubChatSDK" });

4. Compile the code and run the project.

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

Asynchronous and synchronous method execution

Most PubNub Unreal Chat SDK methods are available in both asynchronous and synchronous variants.

• Asynchronous methods (Async suffix) return void and take an optional delegate parameter that fires when the operation completes.

  1PubnubChatSubsystem->InitChatAsync("pub-key", "sub-key", "my_user", OnInitChatResponseDelegate);

  You can also use native callbacks that accept lambdas instead of dynamic delegates. Native callback types have the Native suffix (for example, FOnPubnubChatInitChatResponseNative).

• Synchronous methods (no suffix) block the calling thread until the operation completes and return a result struct directly.

  1FPubnubChatInitChatResult Result = PubnubChatSubsystem->InitChat("pub-key", "sub-key", "my_user");

Initialize PubNub Chat

Use the InitChat() method to create a Chat SDK instance. Three parameters are required: Publish Key, Subscribe Key, and User Id.

Optional parameters configure features like typing indicators and presence tracking.

The subsystem supports multiple simultaneous chat instances keyed by UserID. Call GetChat(UserID) to retrieve a specific instance, and DestroyChat(UserID) to destroy one.

Method signature

C++ / Input parameters

1UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
2

3FPubnubChatInitChatResult Result = PubnubChatSubsystem->InitChat("Publish Key", "Subscribe Key", "User Id");
4UPubnubChat* Chat = Result.Chat;

Blueprint

Input parameters

* required

Parameter	Feature	Description
Publish Key * Type: String Default: n/a	Send messages	Specifies the key used to publish messages on a channel.
Subscribe Key * Type: String Default: n/a	Receive messages	Specifies the key used to subscribe to a channel.
User Id * Type: String Default: n/a	n/a	Unique User ID that becomes your app's current user. It's a string of up to 92 characters that identifies a single client (end user, device, or server) that connects to PubNub. Based on User ID, PubNub calculates pricing for your apps' usage. User ID should be persisted and remain unchanged. If you don't set userId, you won't be able to connect to PubNub.
Config → Auth Key Type: String Default: n/a	Moderation	Specifies the key used to authorize operations in PubNub's Access Manager system.
Config → Typing Timeout Type: Integer Default: 5000	Typing Indicator	Specifies the default timeout after which the typing indicator automatically stops when no typing signals are received. The default and maximum value is set to 5000 milliseconds (5 seconds).
Config → Typing Timeout Difference Type: Integer Default: 1000	Typing Indicator	Specifies the difference in time between actually sending the typing indicator and the value of Typing Timeout. This is designed to cover for any network lag that may occur. If you set the Typing Timeout to 5 seconds and the Typing Timeout Difference to 1 second, the typing signal stops between the fourth and fifth second. The default value is set to 1000 milliseconds (1 second).
Config → StoreUserActivityTimestamps Type: Bool Default: False	User's last online activity, global presence	Specifies if you want to track the user's global presence in your chat app. The user's activity is tracked through the LastActiveTimeStamp parameter on the User object.
Config → StoreUserActivityInterval Type: Integer Default: 600000	User's last online activity, global presence	Specifies how often the user global presence in the app should be updated. Requires StoreUserActivityTimestamps to be set to True. The default value is set to 600000 milliseconds (10 minutes), and the minimum possible value is 60000 milliseconds (1 minute). If you try to set it to a lower value, you'll get the StoreUserActivityInterval must be at least 60000ms error.
Config → EmitReadReceiptEvents Type: TMap<FString, bool> Default: {public: false, group: true, direct: true}	Read receipts	Controls which channel types emit read receipt events. Keys are channel types (public, group, direct); set a value to false to suppress read receipt events for that type.
Config → RateLimiter Type: FPubnubChatRateLimiterConfig Default: Empty (no rate limiting)	n/a	Configures rate limiting for sending messages. Contains RateLimitPerChannel (TMap<FString, int>) mapping channel types to milliseconds between sends, and RateLimitFactor (float, default 1.2) for exponential backoff on repeated rate limit hits (recommended range: 1.0–10.0).

Blueprint users: initialize FPubnubChatConfig with GetDefaultChatConfig()

In Blueprint, use GetDefaultChatConfig() on UPubnubChatSubsystem to initialize FPubnubChatConfig with correct defaults, including the pre-populated EmitReadReceiptEvents map (public=false, group=true, direct=true). Using the built-in Make Struct node for FPubnubChatConfig skips C++ constructors and produces an empty EmitReadReceiptEvents map, which disables read receipt events for all channel types.

Output parameters

Parameter	Description
FPubnubChatInitChatResult Type: struct	Returned object containing Result and Chat.
→ Result Type: FPubnubChatOperationResult	Operation result with Error (bool), ErrorMessage (FString), and StepResults (per-step details).
→ Chat Type: UPubnubChat*	The initialized chat instance. nullptr if initialization failed.

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.

Initialize the Chat SDK with publish key, subscribe key, and user ID.

C++

Actor.h

1

Actor.cpp

1

Blueprint

Other examples

These examples show additional ways to initialize, retrieve, and tear down chat instances using UPubnubChatSubsystem.

Initialize with custom configuration

C++

1

Blueprint

Initialize with an existing PubNub client

C++

1

Blueprint

Retrieve a chat instance

C++

1

Blueprint

Destroy a chat instance

C++

1

Blueprint

Destroy all chat instances

C++

1

Blueprint

Get access manager

Get the Access Manager instance associated with the current chat session with GetAccessManager(). Use it to manage token-based access control for channels and users.

Method signature

1Chat->GetAccessManager();

Output

Type	Description
UPubnubChatAccessManager*	The Access Manager instance for the current chat session.

Sample code

1UPubnubChatAccessManager* AccessManager = Chat->GetAccessManager();

Package a Blueprint project

A bug in Unreal Engine can cause C++ plugins to fail when packaging Blueprint projects. Create a C++ source file in your project to resolve the Plugin X failed to load error.

1. Create an empty C++ class (Tools -> Add C++ Class) with None as the parent.
2. Remove the Intermediate, Build, and Binaries folders.
3. Rebuild and reopen the project.

For more information, refer to Unreal Engine Forums.

Next steps

After initialization, you can:

• Create channels and users
• Add features like messaging, typing indicators, and presence