DocumentationAPI Reference

Getting started

Getting started

The SDK has the following requirements:

  • Minimum iOS version: 12.0
  • XCFrameworks are only forward compatible with equal or newer versions of the Swift Compiler. The ChatSDK will not compile with Xcode versions prior to the version it was compiled with.

Add the Chat SDK dependencies

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

Adding the SDK with Swift Package Manager

To integrate the Chat SDK using Swift Package Manager, follow the instructions in Adding the Chat SDK.

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 dependency manager like Swift Package Manager 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. If you want to implement push notifications, you must also provide the appId. Both can can be obtained by asking the account owner.

Swift

import ChatSDKimport 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.departmentName = "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.departmentName = <#"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.

SettingDescription
departmentIdString that matches the id of a department configured in the Chat dashboard. The chat will then be routed accordingly.
departmentNameString 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.
departmentThe old version of departmentName and will be deprecated.
tagsAn array of strings that will appear to the agent in the chat. Tags can also be added and removed using the ProfileProvider. See Adding and removing tags.
visitorInfoAllows the visitor's name, email address and phone number to be specified. This will be seen by the agent. See VisitorInfo.
visitorPathOneThis string will be placed in the first line under "Visitor path" beside the chat for the agent to see. Defaults to "Direct Path".
visitorPathTwoThis 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.
visitorPathTwoValueThis string appears when hovering over the second line of the "Visitor path".

Note: You can use either departmentName or departmentId to set the department. department will be removed in a future version.

VisitorInfo
SettingDescription
nameThe name that will be associated with the visitor.
emailThe email that will be associated with the visitor.
phoneNumberThe 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 ChatSDKimport 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 {  ZDKClassicMessagingConfiguration *messagingConfiguration = [[ZDKClassicMessagingConfiguration 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 = [ZDKClassicMessaging.instance buildUIWithEngines:engines                                                                       configs:@[messagingConfiguration, chatConfiguration]                                                                         error:&error];  // Present view controller  [self.navigationController pushViewController:viewController animated:YES];}

Important: You need to add a button to dismiss the view controller if you are presenting modally. See Presenting the screen in the Unified SDK docs.

Important: If the Chat SDK is used in conjunction with the Answer Bot SDK, the Answer Bot SDK must be added before the Chat SDK. See Running the engine with other engines in the Chat engine docs.

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 chat session will terminate if any of the following conditions are met:

  • The visitor without push has been idle* for more than 20 minutes (30 minutes total).
  • The visitor with push has been inactive for more than 5 minutes.
  • The visitor has been disconnected for the duration of the inactivity timeout (30 minutes or 5 minutes).
  • The agent ends the chat, at which point the session will terminate after 5 minutes without visitor input, regardless off whether push notifications have been configured. Any new message will place you back in the queue.
  • The visitor ends the chat, at which point the session will immediately terminate.
  • On the Agent Workspace account, if either the visitor or the agent ends the chat, the session will immediately terminate.

*The visitor will become idle after no input is detected for 10 minutes.

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 = trueLogger.defaultLevel = .verbose

Objective-C

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

Integrate with SwiftUI

See the documentation here if you are integrating the SDK in a SwiftUI view hierarchy.

Advanced Topics

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