Getting started

The SDK has the following requirements:

  • Minimum iOS version: 10.0
  • Chat 2.5.1 and newer is built with XCode 11.4+ and Swift 5.2.2+

Add the Chat SDK dependencies

You can add the Chat SDK to your project using CocoaPods, Carthage or manually.

Adding the SDK with CocoaPods

To integrate the Chat SDK using CocoaPods, follow the instructions in Adding the Chat SDK.

Adding the SDK with Carthage

To integrate the Chat SDK using Carthage, follow the instructions in Adding the Chat SDK.

Adding the SDK manually

While we recommend using a third-party dependency manager like Carthage or CocoaPods, you can also manually integrate the Chat SDK by following the instructions in Adding the Chat SDK.

Initializing the SDK

To initialize the Chat SDK, you must provide your account key and your app identifier. These can be obtained by asking the account owner.

Swift

import ChatSDK
import ChatProvidersSDK

Chat.initialize(accountKey: <#"Your account key"#>, appId: <#Your app identifier#>)

Objective-C

#import <ChatSDK/ChatSDK.h>
#import <ChatProvidersSDK/ChatProvidersSDK.h>

[ZDKChat initializeWithAccountKey:<#"Your account key"#> appId:<#Your app identifier#> queue:dispatch_get_main_queue()];

Configuring the SDK

Configuring the conversation

The Chat SDK provides the ChatConfiguration class that you can use to enable or disable certain conversational features.

Swift

let chatConfiguration = ChatConfiguration()
chatConfiguration.isAgentAvailabilityEnabled = false

Objective-C

ZDKChatConfiguration *chatConfiguration = [[ZDKChatConfiguration alloc] init];
chatConfiguration.isAgentAvailabilityEnabled = YES;

For the full documentation on the ChatConfiguration class, see Customizing the look.

Setting information for the chat session

The chat can be configured using the ChatAPIConfiguration class.

Swift

let chatAPIConfiguration = ChatAPIConfiguration()
chatAPIConfiguration.department = "Department name"
chatAPIConfiguration.visitorInfo = VisitorInfo(name: <#"Name"#>, email: <#"Email address"#>, phoneNumber: <#"Phone number"#>)
Chat.instance?.configuration = chatAPIConfiguration

Objective-C

ZDKChatAPIConfiguration *chatAPIConfiguration = [[ZDKChatAPIConfiguration alloc] init];
chatAPIConfiguration.department = <#"Department name"#>;
chatAPIConfiguration.visitorInfo = [[ZDKVisitorInfo alloc] initWithName:<#"Name"#>
                                                                  email:<#"Email address"#>
                                                            phoneNumber:<#"Phone number"#>];
ZDKChat.instance.configuration = chatAPIConfiguration;

To update a configuration once it has been initially set, you must apply changes to a ChatAPIConfiguration object and then again set it with Chat.instance?.configuration = chatAPIConfiguration, as above.

Setting Description
department This can be set to a valid string that matches the name of a department configured in the Chat dashboard. The chat will then be routed accordingly. For more information about getting a list of available departments, see Getting the availability of agents.
tags This can be set to an array of strings which will then appear to the agent in the chat. Tags can also be added and removed using the ProfileProvider. See Adding and removing tags.
visitorInfo Allows the visitor's name, email address and phone number to be specified. This will be seen by the agent. See VisitorInfo.
visitorPathOne This string will be placed in the first line under "Visitor path" beside the chat for the agent to see. Defaults to "Direct Path".
visitorPathTwo This string will be placed in the second line under "Visitor path" beside the chat for the agent to see. Defaults to show the version of the Chat SDK.
visitorPathTwoValue This string appears when hovering over the second line of the "Visitor path".
VisitorInfo
Setting Description
name The name that will be associated with the visitor.
email The email that will be associated with the visitor.
phoneNumber The phone number that will be associated with the visitor.

Important: department, visitorPathOne, visitorPathTwo, and visitorPathTwoValue can't be updated once a chat has started. visitorInfo and tags can be updated throughout a session.

Important: If you're setting a department while also using a trigger to send an initial message, please see here for related information.

Starting a chat

Starting a chat begins with building the messaging interface, and this requires at least one product engine to be passed into the buildUI method. See the Unified SDK documentation for more information relating to product engines and how to use them.

Swift

import ChatSDK
import MessagingSDK

func startChat() throws {
  // Name for Bot messages
  let messagingConfiguration = MessagingConfiguration()
  messagingConfiguration.name = "Chat Bot"

  let chatConfiguration = ChatConfiguration()
  chatConfiguration.isPreChatFormEnabled = true

  // Build view controller
  let chatEngine = try ChatEngine.engine()
  let viewController = try Messaging.instance.buildUI(engines: [chatEngine], configs: [messagingConfiguration, chatConfiguration])

  // Present view controller
  self.navigationController?.pushViewController(viewController, animated: true)
}

Objective-C

- (void) startChat {
  ZDKMessagingConfiguration *messagingConfiguration = [[ZDKMessagingConfiguration alloc] init];
  messagingConfiguration.name = @"Chat Bot";

  ZDKChatConfiguration *chatConfiguration = [[ZDKChatConfiguration alloc] init];
  chatConfiguration.isPreChatFormEnabled = YES;

  // Build view controller
  NSError *error = nil;
  NSArray *engines = @[
      (id <ZDKEngine>) [ZDKChatEngine engineAndReturnError:&error]
  ];

  UIViewController *viewController = [ZDKMessaging.instance buildUIWithEngines:engines
                                                                       configs:@[messagingConfiguration, chatConfiguration]
                                                                         error:&error];
  // Present view controller
  [self.navigationController pushViewController:viewController animated:YES];
}

Note: You need to add a button to dismiss the view controller if you are presenting modally. To read more, see Presenting the screen.

Push Notifications

You can use push notifications with the Chat SDK to notify your users every time the agent sends new message to the conversation. To learn how to enable the push notifications in your app, see Push Notifications.

Offline Forms

Offline forms provide a way for your visitors to contact you when all of your agents are offline. The form supports name and email input, where the email field is required to complete the form. It will create a ticket on your support dashboard once submitted. Offline forms can be enabled or disabled by setting the isOfflineFormEnabled flag in the ChatConfiguration class. The isAgentAvailabilityEnabled flag needs to be enabled for offline forms to work. For more details, see Customizing the Chat experience.

Configuring the queue

The queue provides a way for users to see a rough estimate on how long they will be waiting to talk to an agent. It is based on the number of other visitors ahead of them. It is not possible to disable the queue, but it is possible to change or remove the text. See known issues for more information.

Session termination

The inactivity timeout for a session lasts for 1 hour if you have configured push notifications or for 5 minutes if you have not.

The chat session will terminate if any of the following conditions are met:

  • There's no activity on the chat for the duration of the inactivity timeout (1 hour or 5 minutes)
  • The visitor has been disconnected for the duration of the inactivity timeout
  • The agent ends the chat, at which point the session will terminate after 5 minutes, regardless off whether push notifications have been configured
  • The visitor ends the chat, at which point the session will immediately terminate

Logging

Logging can be enabled with one of the following values:

Log Level
info
debug
warning
error
verbose

The default is info but verbose will provide the most information.

Swift

Logger.isEnabled = true
Logger.defaultLevel = .verbose

Objective-C

ZDKChatLogger.isEnabled = YES;
ZDKChatLogger.defaultLevel = ZDKChatLogLevelVerbose;

Advanced Topics

See the documentation of our APIs for descriptions of classes and models.