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

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.

Provider Description
ChatProvider For APIs related to the chat session.
ProfileProvider For APIs related to the visitor.
PushNotificationsProvider For APIs related to Push.
ConnectionProvider For APIs related to the connection.
SettingsProvider For 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().uploadFile(with: data, name: fileName)


let chatProvider = Chat.chatProvider

// Optional completion handler

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 }

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.