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.

Limit of 3 keysets for Free tier accounts

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

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, make sure App Context, Presence, and Message Persistence are enabled on your keyset.

Download the SDK

Download the SDK from any of the following sources:

Get the source code

You can download the source code from GitHub.

Use Xcode

1. Create or open your project inside Xcode.
2. Navigate to File -> Add Package Dependencies.
3. Search for https://github.com/pubnub/swift-chat-sdk.
4. From the Dependency Rule drop-down list, select the Up to Next Major Version rule, and click Add Package.

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:

1. Import the PubNubSwiftChatSDK and PubNubSDK modules inside your Swift source files:

   1import PubNubSDK
   2import PubNubSwiftChatSDK

2. Create a ChatImpl object, which takes the following parameters:

   Configuration	Description
   pubNubConfiguration	An instance of the PubNub account configuration. You must provide at least the subscribeKey and userId to connect to PubNub.
   chatConfiguration	An instance of chat-specific configuration required to implement advanced features, like typing indicator, user offline/online presence, push notifications, or client-side limiting that prevents spamming.

   Strong reference

   We recommend that you create a strong reference to the ChatImpl object to avoid problems caused by garbage collection or lost state.

3. Call the initialize() method on your ChatImpl object. Refer to Basic usage for an example.

1public struct ChatConfiguration {
2  public var logLevel: LogLevel
3  public var typingTimeout: Int
4  public var storeUserActivityInterval: Int
5  public var storeUserActivityTimestamps: Bool
6  public var pushNotificationsConfig: PushNotificationsConfig
7  public var rateLimitFactor: Int
8  public var rateLimitPerChannel: [ChannelType: Int64]
9  public var customPayloads: CustomPayloads?
10  public var syncMutedUsers: Bool
11  
12  public init(
13    logLevel: LogLevel = .off,
14    typingTimeout: Int = 5,
15    storeUserActivityInterval: Int = 600,
16    storeUserActivityTimestamps: Bool = false,
17    pushNotificationsConfig: PushNotificationsConfig = .init(),
18    rateLimitFactor: Int = 2,
19    rateLimitPerChannel: [ChannelType: Int64] = ChannelType.allCases.reduce(into: [ChannelType: Int64]()) { res, type in res[type] = 0 },
20    customPayloads: CustomPayloads? = nil,
21    syncMutedUsers: Bool = false
22  )
23}
24

25public struct PushNotificationsConfig {
26  public var sendPushes: Bool
27  public var deviceToken: String?
28  public var deviceGateway: PubNub.PushService
29  public var apnsTopic: String?
30  public var apnsEnvironment: PubNub.PushEnvironment
31  
32  public init(
33    sendPushes: Bool = false,
34    deviceToken: String? = nil,
35    deviceGateway: PubNub.PushService = .fcm,
36    apnsTopic: String? = nil,
37    apnsEnvironment: PubNub.PushEnvironment = .development
38  )
39}

show all 39 lines

Chat SDK-specific configuration

Input parameters

Parameter	Description
pubNubConfiguration Type: PubNubConfiguration	Mandatory PubNub account configuration.
→ publishKey Type: String	Specifies the key used to publish messages on a channel.
→ subscribeKey Type: String	Specifies the key used to subscribe to a channel.
→ userId Type: String	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.
chatConfiguration Type: ChatConfiguration	ChatConfiguration contains chat app configuration settings, such as saveDebugLog or typingTimeout that you provide when initializing your chat app with the initialize() method. You can later directly access these properties, like: chat.storeUserActivityInterval.

ChatConfiguration

* required

Parameter	Feature	Description
logLevel Type: LogLevel Default: .off	Error logging	Specifies if any Chat SDK-related errors should be logged. It's disabled by default. Available options include: off, error, warn, info, debug, and verbose.
typingTimeout Type: Int Default: 5	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 5 seconds.
storeUserActivityInterval Type: Int Default: 600	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 60 seconds, and that's the minimum possible value. If you try to set it to a lower value, you'll get the storeUserActivityInterval must be at least 60000ms error.
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.
pushNotificationsConfig Type: PushNotificationsConfig Default: n/a	Push Notifications	List of parameters you must set if you want to enable sending/receiving mobile push notifications for phone devices, either through Apple Push Notification service (APNS) or Firebase Cloud Messaging (FCM).
→ sendPushes Type: Bool Default: 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 that the Chat SDK automatically attaches to every message. Chat SDK includes a default payload setup for deviceGateway 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 Type: String Default: 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 Type: PubNub.PushService Default: fcm	as above	Option for receiving push notifications on Android (fcm) or iOS (apns or apns2) devices. These are the available types: apns - Apple Push Notification service apns2 - Apple Push Notification service v2 fcm - Firebase Cloud Messaging
→ apnsTopic Type: String Default: 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 Type: PubNub.PushEnvironment Default: development	as above	Option for receiving notifications on iOS devices. When registering for push notifications, this option specifies whether to use the development (development) or production (production) APNs environment.
rateLimitFactor Type: Int Default: 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 1 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 Type: [ChannelType: Int64] Default: n/a	Client-side rate limiting	Client-side limit 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.
→ direct Type: Int Default: 0 (no limit)	as above	Rate set on all direct (1:1) channels at which messages can be published.
→ group Type: Int Default: 0 (no limit)	as above	Rate set on all group channels at which messages can be published.
→ public Type: Int Default: 0 (no limit)	as above	Rate set on all public channels at which messages can be published.
→ unknown Type: Int Default: 0 (no limit)	as above	Rate set on all channels created using the Swift SDK instead of Swift Chat SDK.
customPayloads Type: CustomPayloads Default: 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 Type: Function that takes three parameters: EventContent.TextMessageContent object String representing a channel ID DefaultGetMessagePublishBody representing a default handler Default: 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 Type: Function that takes three parameters: JSONCodable representing the message response String representing a channel ID DefaultGetMessageResponseBody representing a default handler Default: 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 EventContent.TextMessageContent). Expand the Message-related types section for more details on the required EventContent.TextMessageContent structure. Define getMessagePublishBody whenever you use getMessageResponseBody.
→ editMessageActionName Type: String Default: 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 reaction used by Chat SDK is "edited". Expand the Message-related types section for more details.
→ deleteMessageActionName Type: String Default: 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 reaction used by Chat SDK is "deleted". Expand the Message-related types section for more details.
syncMutedUsers Type: Bool Default: false	User moderation	Whether the mute list is synchronized across sessions and devices. For more information, refer to Sync muted users.

Sync muted users

The syncMutedUsers parameter determines whether the mute list is synchronized across sessions and devices using a specific App Context User object.

When set to false, the mute list modifications are stored only for the duration of the current session. Once the session ends, the mute list is cleared.

When set to true, the client-side mute list is automatically saved and retrieved from App Context, ensuring that the muted user list persists beyond the current session. App Context uses a designated channel where all mute list data is sent: PN_PRV.$currentUserId.mute1.

Mute list and Access Manager

If you use Access Manager within your chat app and syncMutedUsers is enabled, you must grant the Swift Chat SDK user the following permissions:

• read permission to the PN_PRV.$currentUserId.mute1 channel.
• update, delete, and get permissions for the PN_PRV.$currentUserId.mute1 user.

Make sure to change $currentUserId to the user ID of the chat user that will use the mute list functionality.

Additional configuration options

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

For example, you can 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 Swift SDK configuration document.

Sample code

Required setup

Use this basic example to initialize the client setting only the required parameters.

1// An example of how to initialize the top-level ChatImpl object
2func performChatInitializationExample() async throws {
3  // Create PubNub configuration
4  let pubNubConfiguration = PubNubConfiguration(
5    publishKey: "your-publish-key",
6    subscribeKey: "your-subscribe-key",
7    userId: "your-user-id"
8    // Add other required parameters
9  )
10    
11  // Create Chat configuration
12  let chatConfiguration = ChatConfiguration(
13    // Fill in the necessary parameters for ChatConfiguration
14  )
15    
16  // Important: store the ChatImpl in a property to maintain a strong reference.
17  // If it is not retained, it will be deallocated
18  let chat = ChatImpl(
19    chatConfiguration: chatConfiguration,
20    pubNubConfiguration: pubNubConfiguration
21  )
22

23  try await chat.initialize()
24}

show all 24 lines

Typing indicator timeout

Create the PubNub Chat SDK and set the default typing indicator timeout value to three seconds.

1

2// An example of how to initialize the top-level ChatImpl object
3func performChatInitializationExample() async throws {
4  // Create PubNub configuration
5  let pubNubConfiguration = PubNubConfiguration(
6    publishKey: "your-publish-key",
7    subscribeKey: "your-subscribe-key",
8    userId: "your-user-id"
9    // Add other required parameters
10  )
11    
12  // Create Chat configuration
13  let chatConfiguration = ChatConfiguration(
14    typingTimeout: 3
15  )
16    
17  // Important: store the ChatImpl in a property to maintain a strong reference.
18  // If it is not retained, it will be deallocated
19  let chat = ChatImpl(
20    chatConfiguration: chatConfiguration,
21    pubNubConfiguration: pubNubConfiguration
22  )
23

24  try await chat.initialize()
25}

show all 25 lines

Client-side rate limiting

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

1// An example of how to initialize the top-level ChatImpl object
2func performChatInitializationExample() async throws {
3  // Create PubNub configuration
4  let pubNubConfiguration = PubNubConfiguration(
5    publishKey: "your-publish-key",
6    subscribeKey: "your-subscribe-key",
7    userId: "your-user-id"
8    // Add other required parameters
9  )
10

11  // Create Chat configuration
12  let chatConfiguration = ChatConfiguration(
13    rateLimitFactor: 3,
14    rateLimitPerChannel: [
15      .public: Int64(3 * 1000) // 3 seconds converted to milliseconds
16    ]
17  )
18    
19  // Important: store the ChatImpl in a property to maintain a strong reference.
20  // If it is not retained, it will be deallocated
21  let chat = ChatImpl(
22    chatConfiguration: chatConfiguration,
23    pubNubConfiguration: pubNubConfiguration
24  )
25

26  try await chat.initialize()
27}

show all 27 lines

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.

1// Define custom payloads
2let customPayloads = CustomPayloads(
3  getMessagePublishBody: { content, _, _ in
4    return [
5      "custom": [
6        "payload": [
7          "text": content.text
8        ]
9        // Optionally also save files as ["files": content.files]
10      ]
11    ]
12  },
13  getMessageResponseBody: { json, _, _ in
14    guard
15      let custom = try? json.decode([String: AnyJSON].self),
16      let payload = custom["payload"],
17      let text = payload["text"]?.stringOptional
18    else {
19      fatalError("Message cannot be parsed")
20    }
21    
22    // Optionally parse files
23    return EventContent.TextMessageContent(text: text)
24  }
25)
26

27// Create a configuration that you can later provide to the ChatImpl constructor
28let chatConfiguration = ChatConfiguration(
29  customPayloads: customPayloads
30)

show all 30 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.

1// Define custom payloads
2let customPayloads = CustomPayloads(
3  getMessagePublishBody: { content, channelId, defaultHandler in
4    if channelId == "support-channel" {
5      return [
6        "my": [
7          "custom": [
8            "payload": [
9              "structure": content.text
10            ]
11          ]
12        ],
13        // Optional parameter
14        "files": content.files as Any,
15      ] as [String: Any]
16    }
17    // Default Chat SDK message body structure for other channels
18    return defaultHandler(content)
19  },
20  getMessageResponseBody: { json, channelId, defaultHandler in
21    if channelId == "support-channel" {
22      guard
23        let custom = json.codableValue.dictionaryOptional?["my"] as? [String: Any],
24        let payload = custom["custom"] as? [String: Any],
25        let structure = payload["payload"] as? [String: Any],
26        let text = structure["structure"] as? String
27      else {
28        fatalError("Message cannot be parsed")
29      }
30      return EventContent.TextMessageContent(text: text)
31    }
32    // Default Chat SDK message body structure for other channels
33    return defaultHandler(json)
34  },
35  // Override the default edit action name
36  editMessageActionName: "updated",
37  // Override the default delete action name
38  deleteMessageActionName: "removed"
39)

show all 39 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.