Learn how to install and get started with the Kustomer Chat iOS SDK.

This guide covers how to install and get started with the Kustomer Chat iOS SDK. The current version is 4.0.3.


See Requirements.

Install the Kustomer Chat iOS SDK

Install the Chat iOS SDK files with one of the following methods:

  • Swift Package Manager
  • CocoaPods
  • Manual installation (Xcode framework)


Starting with iOS version 2.6.0, the PubNub library is downloaded as a dependency if installing the SDK using the Swift Package Manager or Cocoapods.

Swift Package Manger installation

You can install the Kustomer Chat iOS files as a package dependency for your app. To learn more, see Adding Package Dependencies to Your App in the Apple Developer portal.

To install with the Swift Package Manager:

  1. Open or create your project in Xcode.

  2. With your project open in Xcode, go to File > Swift Packages > Add Package Dependency.

    For the URL, enter

  3. Under Rules, select Up to next Major. Set the version to span 2.0.0 < 3.0.0, select Next.

CocoaPods installation

You can install the Kustomer Chat iOS files with the CocoaPods Swift dependency manager. To learn more, see the CocoaPods developer documentation.

To install with CocoaPods:

  1. To your Podfile, add the following pod:

    pod 'KustomerChat'

  2. Run pod install or pod update on your project.

    To learn more, see pod install vs. pod update in the CocoaPods developer documentation.

Manual installation

You can install the Kustomer Chat iOS file manually in Xcode as an Xcode framework.

To install manually in Xcode:

  1. In Xcode add KustomerChat.xcframework and to your project in the Framesworks, Libraries, and Embedded Content section. You can find the framework here.

  2. After you add the framework to your project, check that it has the Embed & Sign attribute under Embed.

  3. Add PubNub using your preferred method. You can find details in their documentation here.


If you add PubNub as a git submodule, you must install the PubNub version required by our podspec/package.swift.

Allow file uploads over chat

To allow customers to upload files through chat, in Xcode add privacy descriptions to your Info.plist file for the user's camera roll, media library, and local documents:

Privacy - Camera Usage Description
Privacy - Media Library Usage Description
Privacy - Microphone Usage Description
Privacy - Photo Library Usage Description

Quick start

Import KustomerChat to your AppDelegate and call Kustomer.configure() to initiate chat.

Call Kustomer.configure() with or without options. Initialize chat with options to override settingsin the SDK.

Initialize the Chat iOS SDK

To initialize the Chat iOS SDK:

  1. Add import KustomerChat to your AppDelegate.
  2. In the application(_:didFinishLaunchingWithOptions:) method of your AppDelegate, call Kustomer.configure().

We've included a code sample below.



To use the code sample for your app, replace api key with an API key with the org.tracking role for your Kustomer organization.

import KustomerChat

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  Kustomer.configure(apiKey: "api key", options: nil, launchOptions: launchOptions)

Initialize the Chat iOS SDK with options

You can also use Kustomer.configure() to initialize the Chat iOS SDK with options to override settings in the SDK. For more information, see the KustomerOptions Class Reference.

We've include a code sample below.



To use the code sample for your app, replace api key with an API key with the org.tracking role for your Kustomer organization.

import KustomerChat

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  let options = KustomerOptions()
  options.activeAssistant = .orgDefault
  options.brandId = "nonDefaultBrand"
  options.hideNewConversationButtonInClosedChat = true
  //see full api docs for all options
  Kustomer.configure(apiKey: "api key", options: options, launchOptions: launchOptions)


KustomerOptions class reference


KustomerOptions API attributes

For additional configuration options for initialization, see the full list of all available KustomerOptions API attributes.

activeAssistantThe chat assistant ID. If available, Chat always uses this chat assistant ID as the assistant when a new conversation is created with a button in the chat. Does not affect the Core SDK.

none: Chat does not use an assistant.
orgDefault: Chat uses the default assistant set for the brand under Chat Management settings. .withId(String): Chat uses the provided string as the assistant ID. Format example: options.activeAssistant = .withId("1234")
showInAppNotificationsBoolean that determines if in-app notifications should be shown. Default is true
languageThe language for displaying volume control content, automated messages, snippets, and Knowledge Base articles. If blank, Kustomer Chat uses the device language as the default language.

See Localization for supported language locales and instructions to change the default language or to add a new localization.
enableUIBoolean that determines if the SDK will use the default Kustomer Chat UI.

Default is true. Set to false if you Build your own UI.
pushBundleIdSets the topic for push notifications, usually your app's bundle ID. Default is the bundle ID of your application.
pushEnvironmentTells the push notification service to use either the development or production environment. Default is production.
hideNewConversationButtonInClosedChatBoolean that determines if a "New Conversation" button should appear at the bottom of closed chats. Default is false. Set as true to stop customers from starting new chats from an ended chat screen.
hostDomainSet this option to use a custom host domain. You do not have to do this unless instructed by a Kustomer representative or developer. Default is the default Kustomer API domain.
businessScheduleIdSet this to use a business schedule ID for a custom Business Schedule created in Kustomer. Default is the default business schedule for your org.

Deprecated for Chat 2.0
Overrides the Knowledge Base id.

This method has been deprecated. Use brandId instead to fetch brand-specific chat settings, including a brand-specific Knowledge Base.
brandIdProvides a Brand ID to fetch brand-specific chat settings. Default is the default brand ID for your org.
logLevelsThe type of error logs available. To learn more, see KustomerLogType.

Defaults to [.debug, .info, .error, .warning] .

Set to [] to disable logging.

multithreadingWarning will only be logged if you are building your own UI
messageAttachmentLocalCacheMaximumSizeInBytesMax size of local cache for message attachments. Defaults to 25MB. Minimum of 10MB, maximum of Int.max. Files attached to support chats are saved to the documents folder. Once this local cache exceeds this value, the cache is cleared the next time the customer downloads a new message attachment.
showAnimationFor5StarCSATRatingsControls the chat animation displayed to customers for 5-star CSAT ratings. Defaults to false. Set to true to turn on the CSAT animation.

To learn how to build on Kustomer Chat further with the iOS SDK, see Overview: iOS SDK.

Open Kustomer Chat

The Kustomer Chat iOS SDK provides a modern interface for chat support and native knowledge base access through chat.

Use to open the Kustomer Chat interface from any part of your app.


Build your own chat UI πŸ› 

You can override the Kustomer Chat UI and use the iOS Chat SDK with your own custom view controllers and interface. Use the ChatProviderand ChatListener classes to interact with the Kustomer API directly.

To learn more, see Build your own UI.

Customize Kustomer Chat

Admins in your Kustomer organization can configure basic chat settings directly in Kustomer. To learn more, see Introduction to Kustomer Chat in the Kustomer Help Center.

See Overview: iOS SDK for a collection of guides on how to build on Kustomer Chat with the Chat SDK.

What’s Next