Migration Guide

If you're migrating from an older version of the Chat SDK (prior to v2), this guide will help to highlight some of the key differences.

Initializing the Chat SDK

The Chat SDK initialization should take place in your AppDelegate.swift. The initialization method takes the following parameters:

  • accountKey - This can be found on the Chat dashboard. Ask a Chat admin for the key if you don't have access to the dashboard.
  • apiConfig - Provides a way to configure the chat.
  • thread - The thread to dispatch operations on. Default is the main thread.


ZDCChat.initialize(withAccountKey: accountKey)


Chat.initialize(accountKey: accountKey, queue: .main)

Starting the chat


ZDCChat.start(in: self.navigationController, withConfig: config)


do {  let chatEngine = try ChatEngine.engine()  let viewController = try Messaging.instance.buildUI(engines: [chatEngine], configs: [])
  navigationController?.pushViewController(viewController, animated: true)} catch {  // handle error}

Adding visitor information


ZDCChat.updateVisitor { user in    user?.name = "Name"    user?.email = "Email address"    user?.phone = "Phone number"}


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

Setting the department


ZDCChat.start(in: self.navigationController, withConfig: { config in    config?.department = "Department name"})


let chatAPIConfiguration = ChatAPIConfiguration()chatAPIConfiguration.department = "Department name"Chat.instance?.configuration = chatAPIConfiguration
// OR
let chatProvider = Chat.chatProviderchatProvider.setDepartment("Department Name")

Sending events

Chat SDK v1 allowed you to send events through the ZDCChatAPI instance. With Chat SDK v2, these events are grouped together with similar APIs under the providers.

ChatProviderFor APIs related to the chat session.
ProfileProviderFor APIs related to the visitor.
PushNotificationsProviderFor APIs related to Push.
ConnectionProviderFor APIs related to the connection.
SettingsProviderFor APIs related to the Chat dashboard settings.

Every event that can be sent can take an optional completion closure. The closure provides a Result<Success, Error> return to handle the result of the request.


ZDCChatAPI.instance().sendChatMessage(message)ZDCChatAPI.instance().uploadFile(with: data, name: fileName)ZDCChatAPI.instance().endChat()ZDCChatAPI.instance().setNote(note)ZDCChatAPI.instance().setPushToken(data)


let chatProvider = Chat.chatProvider
// Optional completion handlerchatProvider?.sendMessage(message)
chatProvider?.sendFile(url: fileURL,                       onProgress: { (progress) in },                       completion: { (result) in } )
chatProvider?.endChat { (result) in    switch result {    case .success:        break // Chat ended    case .failure(let error):        break // Handle error    }}
Chat.profileProvider?.setNote(note) { _ in }Chat.pushNotificationsProvider?.registerPushToken(data)

Observing events

Chat v1 leveraged NSNotificationCenter to emit events and handle the subscription of events. Chat v2 implements event observers through the observable pattern.

Subscribing to events


ZDCChatAPI.instance().addObserver(self, forConnectionEvents: #selector(onConnectionStateUpdated))ZDCChatAPI.instance().addObserver(self, forChatLogEvents: #selector(chatLogEvents))ZDCChatAPI.instance().addObserver(self, forAgentEvents: #selector(onAgentEvent))ZDCChatAPI.instance().addObserver(self, forUploadEvents: #selector(chatUploadEvent))ZDCChatAPI.instance().addObserver(self, forAccountEvents: #selector(chatAccountEvent))


let stateToken = Chat.chatProvider?.observeChatState { (state) in    // Handle logs, agent events, queue position changes and other events}
let connectionToken = Chat.connectionProvider?.observeConnectionState { (connection) in    // Handle connection status changes}
let accountToken = Chat.chatProvider?.observeAccount { account in    // Handle department and account status changes}
let settingsToken = Chat.settingsProvider?.observeChatSettings { settings in    // Handle changes to Chat settings}
var tokens: [ObservationToken?] = [stateToken, connectionToken, accountToken, settingsToken]

Unsubscribing from events


ZDCChatAPI.instance().removeObserver(forConnectionEvents: self)ZDCChatAPI.instance().removeObserver(forAgentEvents: self)ZDCChatAPI.instance().removeObserver(forChatLogEvents: self)ZDCChatAPI.instance().removeObserver(forUploadEvents: self)ZDCChatAPI.instance().removeObserver(forAccountEvents: self)


tokens.forEach { $0.cancel() }

Conflicting Names CommonUISDK.Framework

If you are using CocoaPods you may get a "conflicting names commonuisdk.framework" error if you are also using the Support SDK. You can fix this by updating the Support SDK. Follow the Support SDK migration guide, and ensure that you are using the ZendeskSupportSDK pod, and not the deprecated ZendeskSDK pod.

Bot-centered conversational experience

The Chat SDK leverages the Unified SDK to present chat features to the user in a conversational flow. Pre-chat forms, offline forms, and customer satisfaction requests are all sent to the user through a chat bot. Though the bot resembles Answer Bot, it's not. See Configuring the chat bot.