Kustomer Chat SDKs

The Kustomer Chat SDK is available for Android, iOS, and web

Build your own UI

Learn how to build your own mobile Chat UI with the Kustomer Core SDK.

To build your own UI for Kustomer Chat and the Knowledge Base, you can use the Kustomer Core SDK. The Core SDK gives you access to all the data, events, and methods available for our built-in UI.

The Kustomer Core SDK exposes APIs in the form of provider interfaces that allow you to create your own UI and send information into Kustomer APIs.

This guide shows you how to use the Kustomer Core SDK to build your won mobile chat and knowledge base UI for iOS.

📘

Guide: Access the knowledge base 📙

Visit Access the Knowledge Base to learn how to work with the knowledge base with the Kustomer Core SDK.

📘

Guide: Work with conversational assistants 📙

Visit Work with conversational assistants (chatbots) to learn how to work with the conversational assistants with the Kustomer Core SDK.

Prerequisites

Before you get started, you'll need the following:

  • A valid API key with just the org.tracking role. See Requirements

  • Chat SDK installation. To learn more, see Installation.

Overview

To build your own UI with the Kustomer Core SDK, you will need to do the following:

  1. Configure Kustomer in your AppDelegate with options

  2. Create a `Kustomer.ChatProvider()' instance

  3. Implement listeners with KUSChatListener

Step 1: Configure Kustomer Chat in your AppDelegate with options

First, configure Kustomer Chat in your AppDelegate and pass in enableUI = false.

let options = KustomerOptions()
options.enableUI = false

Kustomer.shared.configure(apiKey: apiKey, options: options)

Step 2: Create a `Kustomer.ChatProvider()' instance

After you configure Kustomer, create a Kustomer.ChatProvider() instance anywhere in your application.

You can call different methods of the Kustomer.ChatProvider() to receive events, create messages, and more. Also see the Provider callbacks section.

📘

Kustomer.ChatProvider() methods

Visit the Core API reference for a full list of provider methods.

let provider = Kustomer.ChatProvider()

//See the API Reference link on the left for a full list of methods
provider.addChatListener(foo)
provider.sendMessage(text: "Hello World", conversationId: "123")

Step 3: Implement listeners with KUSChatListener

After you create a Kustomer.ChatProvider() instance in your application, implement the KUSChatListener protocol in one of your classes. You can pass an instance of this class to the provider to take actions for events such as when users receive messages, conversations close, and more.

class MyListener: KUSChatListener {
   func onChatMessageReceived(conversationId: String,
                              chatMessage: KUSChatMessage) {
    print("New message in conversation \(conversationId): \(chatMessage.body)")
  }
  func onConversationCreated(conversationId: String,
                             conversation: KUSConversation) {
    print("A new conversation with id = \(conversationId) was created")
  }
}

let listener = MyListener()

let provider = Kustomer.ChatProvider()
provider.addChatListener(listener)

Get recent data

The Kustomer Core SDK maintains a disk-based persistent cache of data. The persistent cache of data allows you to build interfaces that work offline or with slow internet connections.

We've included an example of how to get the most recent data from the cache.

In the example, convos and messagesForConvo1 will return the best available data.

let convos = provider.conversations()

let convo1 = convos.first
let convo1_id = convo1.id

let messagesForConvo1 = provider.chatMessages(conversationId:convo1_id)

In order to actually receive events in your chat listeners, you need to tell the Kustomer client to start up and go online.

Receive events in listeners

To receive events in chat listeners, use Kustomer.start() either before or after you attach listeners.

Kustomer.shared.start()
Kustomer.shared.start({ result in
  switch result {
    case .success:
      print("started. you'll now get events.")
    case .failure(let error):
      print("could not start. try again later")
      print(error.localizedDescription)
  }
})

Stop events

You can stop Kustomer to block network events from listeners or to prevent any internet connection use.

Kustomer.shared.stop()

Restart events

After you stop Kustomer, you can restart Kustomer at any time. Restart Kustomer to replay all chat listener events you missed while offline.

// At 11am:
Kustomer.shared.stop()

// 10 minutes later, at 11:10am:
Kustomer.shared.start()

// If you had any chat listeners at 11am, they will receive events that you missed from 11am to 11:10am

Automatic retry for events

Kustomer automatically stops when there are internet connection problems. The Core SDK uses an automatic retry scheme (similar to Alamofire), and Kustomer will not stop right away if the internet connection goes down.

You can attach a listener to receive notifications when Kustomer stops due to internet connection problems.

Provider callbacks

All ChatProvider provider methods have callbacks that let you know if the request was successful.

You can use ChatProvider to call methods that send data to the Kustomer platform (for example, send a new chat message).

Data only appears in the listeners and data cache after you successfully send data (for example, a new message or a request to close a conversation).

provider.sendMessage(text: "Hello World", conversationId: "123") { result in
    switch result {
    case .success(let message):
        print("Message w/ id \(message.id) was sent")
    case .failure(let error):
        if error.connectionFailure {
        print("Network problem. Message not saved")
      } else if error.invalidArguments {
        print("Wrong conversation id, attached files too large, etc.")
      }
  }
}

Suggested pattern

We've provided a suggested pattern that shows how to ensure the variable data always has every chat message for a specific conversation based on the conversation id.

In the code examples below, we use a conversation with a conversation id of 100.

For a listener in a class:

class AppDelegate: KUSChatListener {
  var data:[KUSChatMessage] = []
  var provider:Kustomer.ChatProvider?
  
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let options = KustomerOptions()
    options.enableUI = false
    
    Kustomer.shared.configure(apiKey: "API Key", options: options)
    
    provider = Kustomer.ChatProvider()
    data = provider.chatMessages(conversationId:"100")
    provider.addChatListener(self)
    
    Kustomer.shared.start()
  }

  func onChatMessageReceived(conversationId: String, chatMessage: KUSChatMessage) {
    data.append(chatMessage)
  }
}

For a listener in an AppDelegate class:

import KustomerSDK

class Klass: KUSChatListener {
  public var data:[KUSChatMessage]
  var provider:Kustomer.ChatProvider

  init(){
    data = []
    provider = Kustomer.ChatProvider()
    data = provider.chatMessages(conversationId:"100")
    provider.addChatListener(self)
    Kustomer.shared.start()
  }

  func onChatMessageReceived(conversationId: String,
                                chatMessage: KUSChatMessage) {
    data.append(chatMessage)
  }
}

let options = KustomerOptions()
options.enableUI = false
Kustomer.shared.configure(apiKey: "API Key", options: options)
let foo = Klass()

// now foo.data will always have the best available list of chat messages

📘

Authentication

If you are using Kustomer's Authentication it's recommended that you complete the authentication process BEFORE calling the Kustomer.start() method. This will ensure that the authenticated customer's historical messages are loaded when Kustomer.start() is called.

Updated a day ago



Build your own UI


Learn how to build your own mobile Chat UI with the Kustomer Core SDK.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.