Initial configuration

Before building your chat app, you must initialize and configure the Chat SDK.

Start by signing into the Admin Portal or creating an account if you don't have one yet.

Then, create an app on the Admin Portal. You will need a PubNub app to get a keyset that consists of a Subscribe Key and a Publish Key. These keys will let you establish a connection between PubNub and the chat app you're going to create with the Chat SDK.

When you create a new app on the Admin Portal, the first set of demo keys is generated automatically, but a single app can have as many keysets as you like. We recommend that you create separate keysets for production and test environments.

Enable features on your keyset

Each keyset has its own configuration settings in the Admin Portal. To use some features in your chat app, you must enable appropriate settings on your app's keyset on the Admin Portal.

To use the Chat SDK, create or update users, track presence, and store messages in history, you must enable App Context, Presence, and Message Persistence.

Initialize PubNub

Once you have a PubNub account and an app created on the Admin Portal, you can start initializing PubNub Client API context and establish account-level credentials.

To initialize PubNub with the Chat SDK, use the init() method.

You must provide at least these three parameters: publishKey, subscribeKey, or userId. Apart from the required parameters, you can also configure additional options when initializing the Chat SDK. These options will let you add configuration required to implement advanced chat features, like typing indicator, user offline/online presence, push notifications, or client-side limiting that prevents spamming.

The init() method takes the following parameters:

const chat = Chat.init({
    publishKey: string,
    subscribeKey: string,
    userId: string,
    typingTimeout?: number,
    storeUserActivityInterval?: number,
    storeUserActivityTimestamps?: boolean,
    pushNotifications?: {
      sendPushes?: boolean,
      deviceToken?: string,
      deviceGateway?: "apns2" | "gcm",
      apnsTopic?: string,
      apnsEnvironment?: "development" | "production"
    },
    rateLimitFactor?: number,
show all 31 lines

Input parameters

Parameter	Type	Required	Default	Feature	Description
`publishKey`	`string`	Yes	n/a	Send messages	Specifies the key used to publish messages on a channel.
`subscribeKey`	`string`	Yes	n/a	Receive messages	Specifies the key used to subscribe to a channel.
`userId`	`string`	Yes	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.
`typingTimeout`	`number`	No	`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).
`storeUserActivityTimestamps`	`boolean`	No	`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.
`storeUserActivityInterval`	`number`	No	`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.
`pushNotifications`	`object`	No	n/a	Push Notifications	List of parameters you must set if you want to enable sending/receiving mobile push notifications for iOS and Android devices, either through Apple Push Notification service (APNS) in version 2 or Firebase Cloud Messaging (FCM), formerly known as Google Cloud Messaging (GCM).
→ `sendPushes`	`boolean`	No	`false`	as above	The main option for enabling sending notifications. It must be set to `true` if you want a particular client (whether a mobile device, web browser, or server) to send push notifications to mobile devices. These push notifications are messages with a provider-specific payload (different for APNs and FCM) that the Chat SDK automatically attaches to every message. Chat SDK includes a default payload setup for APNs and FCM gateways in every message sent to the registered channels. This is the only required option to enable if you want to send push notifications to Android devices. For iOS devices, you also have to configure `apnsTopic`.
→ `deviceToken`	`string`	No	n/a	as above	Option for receiving notifications on iOS and Android devices. A device token refers to the unique identifier assigned to a specific mobile device by a platform's push notification service. It targets and delivers push notifications to the intended app on that specific device. Suppose you don't set this option and try to run channel registration-related methods. In that case, you'll get the `Device Token has to be defined in Chat pushNotifications config` error. Refer to the official Apple and Google docs to learn how to obtain a device token for the APNs and FCM services.
→ `deviceGateway`	`apns2` or `gcm`	No	`gcm`	as above	Option for receiving push notifications on Android (`gcm`) or iOS (`apns2`) devices.
→ `apnsTopic`	`string`	No	n/a	as above	An Apple specific-option for sending and receiving notifications. This string is a bundle ID that you must define yourself for your iOS app so that Apple could enable push notifications for it in APNs. The string takes the following format: `com.domainname.applicationname`. Apple combines that ID with your Team ID (generated by Apple) and creates an App ID for your application. To send pushes from an iOS device, you must also set `sendPushes` to `true`. To receive pushes on an iOS device, you must also set `deviceGateway` to `apns2`, define `deviceToken`, and `apnsEnvironment`. Suppose you don't configure `apnsTopic`, but set `deviceGateway` to `apns2`. In that case, you'll get the `apnsTopic has to be defined when deviceGateway is set to apns2` error and Chat SDK won't attach the `apns` payload to messages.
→ `apnsEnvironment`	`development` or `production`	No	`development`	as above	Option for receiving notifications on iOS devices. When registering for push notifications, this option specifies whether to use the development or production APNs environment.
`rateLimitFactor`	`number`	No	`2`	Client-side rate limiting	The so-called "exponential backoff" which multiplicatively decreases the rate at which messages are published on channels. It's bound to the `rateLimitPerChannel` parameter and is meant to prevent message spamming caused by excessive retries. The default value of `2` means that if you set `rateLimitPerChannel` for direct channels to `1000` (one second) and try to send three messages on such a channel type within the span of one second, the second message will be published one second after the first one (just like the `rateLimitPerChannel` value states), but the third one will be published two seconds after the second one, meaning the publishing time is multiplied by `2`.
`rateLimitPerChannel`	`object`	No	n/a	Client-side rate limiting	Client-side limit (expressed in milliseconds) that states the rate at which messages can be published on a given channel type. Its purpose is to prevent message spamming in your chat app. This parameter takes an object with these three parameters: `direct`, `group`, and `public`. For example, if you decide that messages on all `direct` channels must be published no more often than every second, set this parameter to `1000`, like `rateLimitPerChannel { direct: 1000 }`.
→ `direct`	`number` (in milliseconds)	No	`0` (no limit)	as above	Rate set on all direct (1:1) channels at which messages can be published.
→ `group`	`number` (in milliseconds)	No	`0` (no limit)	as above	Rate set on all group channels at which messages can be published.
→ `public`	`number` (in milliseconds)	No	`0` (no limit)	as above	Rate set on all public channels at which messages can be published.
`errorLogger`	`ErrorLoggerImplementation`	No	`ErrorLoggerImplementation { setItem(key: string, params: ErrorLoggerSetParams): void, getStorageObject(): Record<string, unknown> }`	Error logging	Specifies if any Chat SDK-related errors should be logged. It's enabled by default. The `setItem` method specifies where errors should be saved and the `getStorageObject` method returns an object with a list of errors. You can replace this implementation with your own.
`customPayloads`	`object`	No	n/a	Send and receive messages	Property that lets you define your custom message payload to be sent and/or received by Chat SDK on one or all channels, whenever it differs from the default `message.text` Chat SDK payload. It also lets you configure your own message actions whenever a message is edited or deleted. For examples, check Custom payload.
→ `getMessagePublishBody`	Function that takes two parameters: `TextMessageContent` object `string` representing a channel ID (if you don't provide a specific channel ID, custom payload applies by default to all PubNub channels)	No	n/a	as above	Function that lets Chat SDK send your custom payload structure. It defines the structure of your own message payload's body (of `any` type) that you're sending through PubNub. Expand the Message-related types section for more details on the required `TextMessageContent` structure. Define `getMessageResponseBody` whenever you use `getMessagePublishBody`.
→ `getMessageResponseBody`	Function that takes the `MessageDTOParams` object as a parameter.	No	n/a	as above	Function that lets Chat SDK receive your custom payload structure. Use it to let Chat SDK translate your custom message payload into the default Chat SDK message format (defined in `TextMessageContent`). Expand the Message-related types section for more details on the required `TextMessageContent` structure. Define `getMessagePublishBody` whenever you use `getMessageResponseBody`.
→ `editMessageActionName`	`string`	No	n/a	as above	A type of action you want to be added to your Message object whenever a published message is edited, like `"changed"` or `"modified"`. The default message action used by Chat SDK is `"edited"`. Expand the Message-related types section for more details.
→ `deleteMessageActionName`	`string`	No	n/a	as above	A type of action you want to be added to your Message object whenever a published message is deleted, like `"removed"`. The default message action used by Chat SDK is `"deleted"`. Expand the Message-related types section for more details.
→ `reactionsActionName`	`string`	No	n/a	as above	A type of action you want to be added to your Message object whenever a reaction is added to a published message, like `"reacted"`. The default message action used by Chat SDK is `"reactions"`. Expand the Message-related types section for more details.
`cryptoModule`	`CryptoModule.aesCbcCryptoModule`	No	n/a	Message and file encryption/decryption	Cryptography module used for encrypting and decrypting messages and files. It takes the `cipherKey` parameter as an argument. For more information and examples, refer to the Data security section.
→ `cipherKey`	`string`	No	n/a	as above	String used to automatically encrypt and decrypt all message and file data in your chat app.

Additional configuration options

Since the Chat SDK heavily relies on the latest JavaScript SDK for all the underlying methods, when initializing the Chat SDK client, you can also make use of all optional parameters that come with the JavaScript SDK.

For example, you may want to use Access Manager and initialize the Chat SDK with secretKey (in the server-side code) or authKey (in the client-side code). You can also decide how long the server will consider the client alive for presence (presenceTimeout) or how often the client will announce itself to the server (heartbeatInterval).

For the whole list of all such inherited optional parameters which you can define when initializing the Chat SDK instance, check the JavaScript SDK configuration document.

Output parameters

Type	Description
`Promise<Chat>`	Object returning a new PubNub chat instance.

Basic usage

Required setup

Use this basic example to include the PubNub Chat SDK package in your code and initialize the client setting only the required parameters.

// include the PubNub Chat SDK package in your code before initializing the client. Underneath, that also installs the PubNub JavaScript SDK "pubnub" package as a dependency.
import { Chat } from "@pubnub/chat"

// initialize your Chat SDK client using your app keys from the Admin Portal and a unique user ID for your client that you'll come up with
const chat = Chat.init({
    publishKey: "demo",
    subscribeKey: "demo",
    userId: "myUniqueUserId"
})

Typing indicator timeout

Initialize the PubNub Chat SDK and set the default typing indicator timeout value to 3000 milliseconds (three seconds).

import { Chat } from "@pubnub/chat"

const chat = Chat.init({
    publishKey: "demo",
    subscribeKey: "demo",
    userId: "myUniqueUserId",
    typingTimeout: "3000"
})

Client-side rate limiting

Initialize the PubNub Chat SDK and set the hard limit for message publishing on public channels to 3000 milliseconds (three seconds). If there are more publish retries within this limit, each next retry limit should be multiplied by 3.

import { Chat } from "@pubnub/chat"

const chat = Chat.init({
    publishKey: "demo",
    subscribeKey: "demo",
    userId: "myUniqueUserId",
    rateLimitPerChannel: {
      public: 1000
    },
    rateLimitFactor: 3
})

Custom payload

When initializing Chat SDK, you can pass your custom message payload structure using the customPayloads object and related properties. This will let Chat SDK correctly interpret your app's messages when sending and receiving them.

Define custom payload for all channels

Let's say your app doesn't follow the default message.text message body structure imposed by Chat SDK but instead uses the my.custom.payload.structure.text structure.

To successfully communicate with PubNub and send/receive messages through Chat SDK, pass your custom payload to all channels. Additionally, define your custom action names to be added to messages when they're edited or deleted.

import { Chat } from "@pubnub/chat"

const chat = Chat.init({
  publishKey: "demo",
  subscribeKey: "demo",
  userId: "myUniqueUserId",
  // If you don't define custom payload, messages on all channels will have the default "message.text" format
  customPayloads: {
    // Pass your custom message body structure so the Chat SDK can interpret your messages when sending them
    getMessagePublishBody: ({ type, text, files }) => {
      return {
        my: {
          custom: {
            payload: {
              structure: text,
show all 41 lines

Define custom payload for one channel

Let's say your app doesn't follow the default message.text message body structure imposed by Chat SDK for support-channel but instead uses the my.custom.payload.structure.text structure to communicate with PubNub.

Pass your custom payload to support-channel to successfully communicate with PubNub and send/receive messages through Chat SDK. Additionally, define your custom action names to be added to messages when they're edited or deleted.

The code sets up a PubNub chat instance with specific handlers for processing message payloads differently based on the channel.

import { Chat } from "@pubnub/chat"

const chat = Chat.init({
  publishKey: "demo",
  subscribeKey: "demo",
  userId: "myUniqueUserId",
  // If you don't define custom payload, messages on all channels will have the default "message.text" format
  customPayloads: {
    // Pass your custom message body structure so the Chat SDK can interpret your messages when sending them on "support-channel"
    getMessagePublishBody: ({ type, text, files }, channelId) => {
      // Define which channel should use custom payload
      if (channelId === "support-channel") {
        return {
          my: {
            custom: {
show all 61 lines

Next steps

Now that you've initialized and configured the Chat SDK, you can start creating channels, adding users, and powering your app with all sorts of features.

Run our sample chat app that will guide you through the chat app creation process and help you get started.

How to work with various frameworks

Chat SDK is framework-agnostic, meaning you can use it with any framework that supports TypeScript, such as React, React Native, Vue, or Angular.

If you want to create a chat app with our Chat SDK or add a chat to an existing application built in one of these frameworks:

Make sure you have these dependencies: yarn (>=1.22.19), Node.js (>=18.10.0), and code editor (for example, Visual Studio Code)
Add framework and PubNub-specific imports to your project file and initialize the Chat SDK.

React
React Native
Vue
Angular

// React imports
import { useEffect, useState } from "react";
// PubNub imports
// Give access to selected Chat SDK entities
import { Chat } from "@pubnub/chat";

// Initialize Chat SDK
export function SomeChatComponent() {
  const [chat, setChat] = useState<Chat>()

  useEffect(() => {
    // Define your PubNub API credentials and user ID here
    const publishKey = "put-your-publish-key-here";
    const subscribeKey = "put-your-subscribe-key-here";
    const userId = "put-your-user-id-here";
show all 28 lines

// React imports
import { useEffect, useState } from "react";
// PubNub imports
// Give access to selected Chat SDK entities
import { Chat } from "@pubnub/chat";

// Initialize Chat SDK
export function SomeChatComponent() {
  const [chat, setChat] = useState<Chat>()

  useEffect(() => {
    // Define your PubNub API credentials and user ID here
    const publishKey = "put-your-publish-key-here";
    const subscribeKey = "put-your-subscribe-key-here";
    const userId = "put-your-user-id-here";
show all 28 lines

// Vue imports
import { reactive } from "vue"
// PubNub imports
// Give access to selected Chat SDK entities
import { Chat } from "@pubnub/chat"

// Define your PubNub API credentials and user ID here
const publishKey = "put-your-publish-key-here"
const subscribeKey = "put-your-subscribe-key-here"
const userId = "put-your-user-id-here"

// Initialize Chat SDK
interface State {
  chat: Chat | null
}
show all 30 lines

// Angular imports
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
// PubNub imports
// Give access to selected Chat SDK entities
import { Chat } from "@pubnub/chat";

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule
  ],
show all 39 lines

If you want further guidance on how to create channels, add users, send messages, and create more advanced features in your chat app, check our sample app built in React:

React Getting Started app and the related guide

Enable features on your keyset

Initialize PubNub​

Input parameters​

Additional configuration options​

Output parameters​

Basic usage​

Required setup​

Typing indicator timeout​

Client-side rate limiting​

Custom payload​

Define custom payload for all channels​

Define custom payload for one channel​

Next steps​

How to work with various frameworks​