---
source_url: https://www.pubnub.com/docs/chat/unity-chat-sdk/build/configuration
title: Initial configuration
updated_at: 2026-06-12T11:23:16.971Z
---

> 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 Unity SDK and Unity Chat SDK before building your chat app.

:::warning Unity SDK is a prerequisite
You must install the [Unity SDK](https://www.pubnub.com/docs/sdks/unity) before installing the Unity Chat SDK.
:::

## 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
:::

## Download the SDKs

Install the [Unity SDK](https://www.pubnub.com/docs/sdks/unity) before installing the Unity Chat SDK.

### Source code

Download the source code from GitHub: [Unity SDK](https://github.com/pubnub/unity) and [Unity Chat SDK](https://github.com/pubnub/unity-chat).

### Package Manager

1. Open Unity Editor and navigate to **Window -> Package Manager**.
2. In the Package Manager window, click **+** and select **Add package from git URL**.
3. Paste the PubNub Unity package links and click **Add**. Do it for both SDKs.

```shell
https://github.com/pubnub/unity.git?path=/PubNubUnity/Assets/PubNub
  
https://github.com/pubnub/unity-chat.git?path=/unity-chat/PubnubChatUnity/Assets/PubnubChat
```

![Add Unity package](https://www.pubnub.com/assets/images/unity-add-package-31392e212b8b2b72484f357e843b04e2.gif)

## WebGL configuration

:::warning Enable WebGL build mode only for builds
Using `UnityWebGLHttpClientService` outside of WebGL builds (including the editor) might cause unexpected behavior due to `UnityWebRequest` being thread-unsafe.
:::

The Unity Chat SDK is compatible with WebGL builds. Configure your project for WebGL:

1. Go to Edit -> Project Settings -> Player and set Managed Stripping Level to Minimal. Additional HTTP setupIf for some reason you can't turn on the Secure option in either PNConfiguration or the Scriptable Object config file, then you need to also go to Project Settings -> Player -> WebGL Settings and set the Allow downloads over HTTP option to Always allowed.
2. Install the WebGL Threading Patcher. Navigate to Window -> Package Manager, click +, select Add package from git URL, paste the link to the Threading Patcher's GIT repository, and click Add.

These steps configure your project for WebGL builds only. Configure other targets as needed.

## Initialize PubNub

Use the `CreateInstance()` method to create a Chat SDK instance. Pass `PNConfiguration` for keys and user ID, and `PubnubChatConfig` for chat-specific features.

```csharp
using System.Threading.Tasks;
using PubnubApi;
using PubnubChatApi;
using UnityEngine;

var pnConfiguration = new PNConfiguration(new UserId("userId"))
{
    PublishKey = "publishKey",
    SubscribeKey = "subscribeKey"
};

var chatConfig = new PubnubChatConfig(storeUserActivityTimestamp: true);

var chatResult = await UnityChat.CreateInstance(chatConfig, pnConfiguration);

if (!chatResult.Error)
{
    var chatInstance = chatResult.Result;
    Debug.Log("Chat instance created successfully!");
}
else
{
    Debug.LogError($"Failed to create chat instance");
}
```

### Initialize PubNub for WebGL

```csharp
using System.Threading.Tasks;
using PubnubApi;
using PubnubChatApi;
using UnityEngine;

var pnConfiguration = new PNConfiguration(new UserId("userId"))
{
    PublishKey = "publishKey",
    SubscribeKey = "subscribeKey"
};

var chatConfig = new PubnubChatConfig(storeUserActivityTimestamp: true);

var chatResult = await UnityChat.CreateInstance(chatConfig, pnConfiguration, webGLBuildMode: true);

if (!chatResult.Error)
{
    var chatInstance = chatResult.Result;
    Debug.Log("Chat instance created successfully for WebGL!");
}
else
{
    Debug.LogError($"Failed to create chat instance");
}
```

If you already have a [PubNub instance set up for WebGL](https://www.pubnub.com/docs/sdks/unity/api-reference/configuration#webgl-configuration), you can pass it to the overloaded `CreateInstance` method.

### Method signatures

Three overloads of `CreateInstance` are available:

* `CreateInstance(PubnubChatConfig chatConfig, PNConfiguration pubnubConfig, bool webGLBuildMode = false, bool unityLogging = false)`
* `CreateInstance(PubnubChatConfig chatConfig, PNConfigAsset configurationAsset, string userId)`
* `CreateInstance(PubnubChatConfig chatConfig, Pubnub pubnub)`

The `PubnubChatConfig` parameters apply to all overloads.

#### PubnubChatConfig

| Parameter | Feature | Description |
| --- | --- | --- |
| TypingTimeout | int | Optional | `5000` | [Typing Indicator](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/channels/typing-indicator) | Specifies the default timeout after which the [typing indicator](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/channels/typing-indicator) automatically stops when no typing signals are received. The default value is set to `5000` milliseconds (5 seconds). |
| TypingTimeoutDifference | int | Optional | `1000` | [Typing Indicator](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/channels/typing-indicator) | Specifies the difference in time between actually sending the typing indicator and the value of `TypingTimeout`. This is designed to cover for any network lag that may occur. The default value is set to `1000` milliseconds (1 second). |
| StoreUserActivityTimestamp | bool | Optional | `false` | [User's last online activity, global presence](https://www.pubnub.com/docs/chat/unity-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/unity-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/unity-chat-sdk/learn/chat-entities/user) parameter on the `User` object. |
| StoreUserActivityInterval | int | Optional | `60000` | [User's last online activity, global presence](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/presence#global-presence) | Specifies how often the user global presence in the app should be updated. Requires `StoreUserActivityTimestamp` to be set to `true`. The default value is set to `60000` milliseconds (1 minute). |
| SyncMutedUsers | bool | Optional | `false` | [Moderation as user](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/moderation-user) | Specifies if you want to persist the [mute list](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/moderation-user#persist-the-mute-list) for regular chat users beyond the scope of a single session. When set to `true`, the mute list is saved and retrieved during client initialization. |
| EmitReadReceiptEvents | Dictionary<string, | Optional | `{"public": false, "group": true, "direct": true}` | [Read Receipts](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/read-receipts) | Controls whether read receipt events are emitted per channel type. Keys are channel type strings (`"public"`, `"group"`, `"direct"`), values are booleans. By default, read receipts are enabled for group and direct channels but disabled for public channels. |
| RateLimitFactor | int | Optional | `2` | [Send messages](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/send-receive) | Exponential backoff factor used by the rate limiter when a channel's send limit is exceeded. A value of `2` means each retry waits twice as long as the previous attempt. |
| RateLimitsPerChannel | RateLimitPerChannel | Optional | `all 0 (disabled)` | [Send messages](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/send-receive) | Per-channel-type rate limit in milliseconds applied between `SendText()` calls. Set to `0` to disable rate limiting for that channel type. See below for the `RateLimitPerChannel` fields. |
| PushNotifications | PushNotificationsConfig | Optional |  | [Mobile Push Notifications](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/push-notifications) | Configuration for mobile push notifications. See below for `PushNotificationsConfig` options. |

#### RateLimitPerChannel

Configure per-channel-type rate limiting by setting the `RateLimitsPerChannel` property of `PubnubChatConfig`:

| Parameter | Description |
| --- | --- |
| `DirectConversation`Type: `int`Default: `0` | Minimum milliseconds between `SendText()` calls on `direct` channels. `0` disables rate limiting. |
| `GroupConversation`Type: `int`Default: `0` | Minimum milliseconds between `SendText()` calls on `group` channels. `0` disables rate limiting. |
| `PublicConversation`Type: `int`Default: `0` | Minimum milliseconds between `SendText()` calls on `public` channels. `0` disables rate limiting. |
| `UnknownConversation`Type: `int`Default: `0` | Minimum milliseconds between `SendText()` calls on channels with an unrecognized type. `0` disables rate limiting. |

#### PushNotificationsConfig

Configure mobile push notifications by setting the `PushNotifications` property of `PubnubChatConfig`:

| Parameter | Description |
| --- | --- |
| `SendPushes`Type: `bool`Default: `false` | Specifies whether push notifications are enabled for sending messages. When `true`, the SDK automatically adds push notification payloads to messages sent on registered channels. |
| `DeviceToken`Type: `string`Default: n/a | The unique device token obtained from the push notification service (APNs or FCM). This identifies the device that will receive push notifications. |
| `DeviceGateway`Type: `PNPushType`Default: `PNPushType.FCM` | The push notification gateway to use. Options include `PNPushType.FCM` for Firebase Cloud Messaging (Android) or `PNPushType.APNS2` for Apple Push Notification service (iOS). |
| `APNSTopic`Type: `string`Default: n/a | The bundle identifier for your iOS app. Required when using APNs. |
| `APNSEnvironment`Type: `PushEnvironment`Default: `PushEnvironment.Development` | The APNs environment to use. Options are `PushEnvironment.Development` or `PushEnvironment.Production`. |

#### PNConfiguration

| Parameter | Feature | Description |
| --- | --- | --- |
| `PublishKey` *Type: `string`Default: n/a | [Send messages](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/send-receive) | Specifies the key used to publish messages on a channel. |
| `SubscribeKey` *Type: `string`Default: n/a | [Receive messages](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/send-receive) | Specifies the key used to subscribe to a channel. |
| `UserId` *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. |
| `AuthKey`Type: `string`Default: n/a | [Access Manager](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/permissions) | Authentication key for Access Manager. Use it for all requests made to PubNub APIs to authenticate users in your application and grant them access to PubNub resources (other users' metadata and channels). |

#### Additional options (when using PNConfiguration)

| Parameter | Description |
| --- | --- |
| `webGLBuildMode`Type: `bool`Default: `false` | Enables WebGL transport (sets `httpTransportService` to `UnityWebGLHttpClientService`). |
| `unityLogging`Type: `bool`Default: `false` | Enables Unity-specific logger (`UnityPubNubLogger`). |

#### PNConfigAsset + userId

| Parameter | Description |
| --- | --- |
| `configurationAsset` *Type: `PNConfigAsset`Default: n/a | Scriptable Object containing your PubNub keys and configuration. |
| `userId` *Type: `string`Default: n/a | Client User ID used to initialize the PubNub instance created from the asset. |

#### Existing Pubnub instance

| Parameter | Description |
| --- | --- |
| `pubnub` *Type: `Pubnub`Default: n/a | Existing PubNub client instance to use for the chat. |

### Output parameters

| Type | Description |
| --- | --- |
| `ChatOperationResult<Chat>` | Returns a new PubNub chat instance on success or a null with error data on failure. |

## Next steps

After initialization, you can:

* Create [channels](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/channels/create) and [users](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/create)
* Add features like [messaging](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/messages/send-receive), [typing indicators](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/channels/typing-indicator), and [presence](https://www.pubnub.com/docs/chat/unity-chat-sdk/build/features/users/presence)