--- source_url: https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/configuration title: Initial configuration updated_at: 2026-06-18T11:25:52.301Z --- > Documentation Index > For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt > For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt # Initial configuration Initialize and configure the Unreal Chat SDK before building your chat app. ## Prerequisites 1. [Sign in](https://admin.pubnub.com/#/login) or [create an account](https://admin.pubnub.com/#/register) on the Admin Portal. 2. [Create an app](https://www.youtube.com/watch?v=ou5RMN1LQ1Y&t=19s&ab_channel=PubNub) to get your **Publish Key** and **Subscribe Key**. :::warning Limit of 3 keysets for Free tier accounts Effective February 3, 2025, all [Free tier](https://www.pubnub.com/pricing/) 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. :::warning 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](https://dev.epicgames.com/documentation/pl-pl/unreal-engine/installing-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. :::note 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](#package-a-blueprint-project) for more information. ::: ## Download the SDK The PubNub Unreal Engine Chat SDK is part of the [PubNub Gaming SDK](https://www.fab.com/listings/9501a8d6-f9e6-4cf8-8b56-d173bdb71fc4) on FAB, which includes both the core PubNub SDK and the Chat SDK plugins. 1. Install the PubNub Gaming SDK plugin from FAB. For information on installing plugins, refer to the Unreal Engine documentation. 2. Enable the PubnubSDK and PubnubChatSDK plugins in your project. Alternative: install from GitHub If you prefer to install from source, clone both repositories into your project's `Plugins` folder: 1. Clone the [Unreal SDK](https://github.com/pubnub/unreal-engine) and the [Unreal Engine Chat](https://github.com/pubnub/unreal-engine-chat) repositories. 2. Rename the cloned folders to `Pubnub` and `PubnubChatSDK` respectively. :::warning Required dependency The Chat SDK is not a standalone plugin. It requires the core PubNub SDK (`Pubnub` folder) to be present in your project's `Plugins` folder. Both must be installed together. ::: ### 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: OSSelectionMacOSServices -> Generate xCode projectWindowsGenerate 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. ##### Usage in Blueprints and C++ 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](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/configuration#initialize-pubnub-chat) using `InitChat` on `UPubnubChatSubsystem`. Afterwards, you can use the returned `UPubnubChat` object reference to call all Chat SDK functions. :::warning 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. #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::InitChatSample() { // Get PubnubChatSubsystem from GameInstance UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Initialize Chat - InitChat may fail under some conditions so make sure to check the Result for errors before using the Chat FPubnubChatInitChatResult InitChatResult = PubnubChatSubsystem->InitChat(TEXT("demo"), TEXT("demo"), TEXT("Player_001")); UPubnubChat* PubnubChat = InitChatResult.Chat; } Chat now allows you to call all Chat SDK functions, for example, Chat->GetChannel("my_channel"). :::note 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 ```cpp UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); FPubnubChatInitChatResult Result = PubnubChatSubsystem->InitChat("Publish Key", "Subscribe Key", "User Id"); UPubnubChat* Chat = Result.Chat; ``` #### Blueprint ### Input parameters | Parameter | Feature | Description | | --- | --- | --- | | `Publish Key` *Type: `String`Default: n/a | [Send messages](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/messages/send-receive) | Specifies the key used to publish messages on a channel. | | `Subscribe Key` *Type: `String`Default: n/a | [Receive messages](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/messages/send-receive) | Specifies the key used to subscribe to a channel. | | `User Id` *Type: `String`Default: n/a | n/a | [Unique User ID](https://www.pubnub.com/docs/general/setup/users-and-devices) 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`Type: `FPubnubChatConfig`Default: Default config | n/a | Optional struct for configuring advanced chat settings. | | `> Auth Key`Type: `String`Default: n/a | [Moderation](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/moderation) | Specifies the key used to authorize operations in PubNub's Access Manager system. | | `> Typing Timeout`Type: `Integer`Default: `5000` | [Typing Indicator](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/channels/typing-indicator) | Specifies the default timeout after which the [typing indicator](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/channels/typing-indicator) automatically stops when no typing signals are received. The default and maximum value is set to `5000` milliseconds (5 seconds). | | `> Typing Timeout Difference`Type: `Integer`Default: `1000` | [Typing Indicator](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/channels/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). | | `> StoreUserActivityTimestamps`Type: `Bool`Default: `False` | [User's last online activity, global presence](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/users/presence#global-presence) | Specifies if you want to track the user's [global presence](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/users/presence#global-presence) in your chat app. The user's activity is tracked through the [LastActiveTimeStamp](https://www.pubnub.com/docs/chat/unreal-chat-sdk/learn/chat-entities/user) parameter on the `User` object. | | `> StoreUserActivityInterval`Type: `Integer`Default: `600000` | [User's last online activity, global presence](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/users/presence#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. | | `> EmitReadReceiptEvents`Type: `TMap`Default: `{public: false, group: true, direct: true}` | [Read receipts](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/messages/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. | | `> RateLimiter`Type: `FPubnubChatRateLimiterConfig`Default: Empty (no rate limiting) | n/a | Configures rate limiting for sending messages. Contains `RateLimitPerChannel` (`TMap`) 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). | :::note 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 :::tip 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 ```cpp // blueprint.imo3pku9 UFUNCTION(BlueprintCallable, Category = "PubnubChat|Samples|ChatSubsystem") void InitChatSample(); ``` ###### Actor.cpp ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::InitChatSample() { // Get PubnubChatSubsystem from GameInstance UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Initialize Chat - InitChat may fail under some conditions so make sure to check the Result for errors before using the Chat FPubnubChatInitChatResult InitChatResult = PubnubChatSubsystem->InitChat(TEXT("demo"), TEXT("demo"), TEXT("Player_001")); UPubnubChat* PubnubChat = InitChatResult.Chat; } ``` ###### Blueprint ### Other examples These examples show additional ways to initialize, retrieve, and tear down chat instances using `UPubnubChatSubsystem`. #### Initialize with custom configuration ##### C++ ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::InitChatWithConfigSample() { // Get PubnubChatSubsystem from GameInstance UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Create config with AuthKey and enable Chat to store user activity FPubnubChatConfig Config; Config.AuthKey = TEXT("p0F2AkF0GmheUpNDdHRsGDxDcmVzpURjaGFuoWtnbG9iYWxfY2hhdANDZ3JwoENzcGOgQ3VzcqBEdXVpZKBDcGF0pURjaGFuoENncnCgQ3NwY6BDdXNyoER1dWlkoERtZXRhoENzaWdYILa9OLrP_dhe31sW_seO2r9KhD6mp9Yi9vZxcX9QY04R"); Config.StoreUserActivityInterval = true; // Initialize Chat - InitChat may fail under some conditions so make sure to check the Result for errors before using the Chat FPubnubChatInitChatResult InitChatResult = PubnubChatSubsystem->InitChat(TEXT("demo"), TEXT("demo"), TEXT("Player_001"), Config); UPubnubChat* PubnubChat = InitChatResult.Chat; } ``` ##### Blueprint #### Initialize with an existing PubNub client ##### C++ ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" #include "PubnubSubsystem.h" #include "PubnubClient.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::InitChatWithPubnubClientSample() { // Get GameInstance and both subsystems (Chat and base Pubnub) UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem(); // Create a Pubnub client (e.g. shared with presence or pub/sub elsewhere in your game) FPubnubConfig ClientConfig; ClientConfig.PublishKey = TEXT("demo"); ClientConfig.SubscribeKey = TEXT("demo"); ClientConfig.UserID = TEXT("Player_001"); UPubnubClient* PubnubClient = PubnubSubsystem->CreatePubnubClient(ClientConfig); // Initialize Chat using that client; check Result for errors before using Chat FPubnubChatInitChatResult InitChatResult = PubnubChatSubsystem->InitChatWithPubnubClient(TEXT("Player_001"), PubnubClient); UPubnubChat* PubnubChat = InitChatResult.Chat; } ``` ##### Blueprint #### Retrieve a chat instance ##### C++ ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::GetChatSample() { // Get PubnubChatSubsystem from GameInstance (e.g. from your player controller or HUD) UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Retrieve the chat for this player (must have been initialized earlier, e.g. on login) UPubnubChat* Chat = PubnubChatSubsystem->GetChat(TEXT("Player_001")); // Use the chat only if it exists if (Chat) { // Chat is ready for sending messages, joining channels, etc. } } ``` ##### Blueprint #### Destroy a chat instance ##### C++ ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::DestroyChatSample() { // Get PubnubChatSubsystem from GameInstance UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Destroy chat for this user (e.g. when player logs out or leaves the match) PubnubChatSubsystem->DestroyChat(TEXT("Player_001")); } ``` ##### Blueprint #### Destroy all chat instances ##### C++ ```cpp #include "Kismet/GameplayStatics.h" #include "Engine/GameInstance.h" #include "PubnubChatSubsystem.h" // ACTION REQUIRED: Replace ASample_ChatSubsystem with name of your Actor class void ASample_ChatSubsystem::DestroyAllChatsSample() { // Get PubnubChatSubsystem from GameInstance UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this); UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem(); // Tear down all chats (e.g. when returning to main menu or shutting down) PubnubChatSubsystem->DestroyAllChats(); } ``` ##### Blueprint ## Get access manager Get the [Access Manager](https://www.pubnub.com/docs/chat/unreal-chat-sdk/learn/access-control) instance associated with the current chat session with `GetAccessManager()`. Use it to manage token-based access control for channels and users. ### Method signature ```cpp Chat->GetAccessManager(); ``` #### Output | Type | Description | | --- | --- | | `UPubnubChatAccessManager*` | The Access Manager instance for the current chat session. | ### Sample code ```cpp UPubnubChatAccessManager* 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](https://forums.unrealengine.com/t/plugin-failed-to-load-because-module-could-not-be-found/472360). ## Next steps After initialization, you can: * Create [channels](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/channels/create) and [users](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/users/create) * Add features like [messaging](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/messages/send-receive), [typing indicators](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/channels/typing-indicator), and [presence](https://www.pubnub.com/docs/chat/unreal-chat-sdk/build/features/users/presence)