Quick start - Chat SDK for iOS

This hands-on tutorial shows you how to build a functioning iOS application in 30 minutes that lets users chat with a support agent. It uses the Zendesk Chat SDK for iOS, a shared code library that lets you easily incorporate Zendesk Chat in iOS applications.

Zendesk gives you other options for providing customer support in mobile apps:

• You can use the Support SDK to incorporate other Zendesk customer support features in iOS applications. To learn how, see Quick start - Support SDK for iOS.

• You can use the Unified SDK to incorporate Zendesk bots with Chat and Support to create a unified messaging experience.

You need macOS and Xcode to build iOS applications. You can download Xcode from the Apple Developer website or from the Mac App Store.

You'll also need a Zendesk Chat account. A free trial account is available. See the Zendesk Chat website.

Though this quick start guide provides step-by-step instructions to build a simple application, it's not an iOS app tutorial. If you're new to iOS development, I highly recommend working through the lessons in Start Developing iOS Apps (Swift) on the Apple website.

The guide walks you through the following basic steps for adding chat functionality to an iOS application:

1. Creating a sample project
2. Adding the Chat SDK with CocoaPods
3. Initializing the Chat SDK
4. Creating a navigation controller for the Chat interface
5. Adding a button to start a chat
6. Connecting the button
7. Pushing the chat view atop the current view
8. Start a chat
9. Next steps

The tutorial uses version 2.12 of the Chat SDK. It was tested in version 13.4.1 of Xcode.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk can't provide support for third-party technologies such as Swift, iOS, and Xcode. Please post any issue in the Zendesk SDKs community, or search for a solution online.

Creating a sample project

This section shows you how to create a quick sample project in Xcode. You'll use the project to try out the Chat SDK.

1. In Xcode, select File > New > Project.

   If you're at the Welcome to Xcode window, choose the second task, Create a new Xcode project.

2. Make sure iOS is selected on the top bar, select App, and click Next.

   

3. Set the following options for the project:

   • Product Name - Enter My Sample Chat App or something similar
   • Organization Identifier - (required) Enter something like com.sample
   • Interface - Select Storyboard (not the default SwiftUI)
   • Language - Select Swift

   Use the default values for the remaining options.

4. Click Next, choose where you want to save the project, and click Create.

Xcode creates all the files and basic settings for your project. You can view the files in the Project navigator on the left side of the screen. If you don't see the files, click the first icon (the folder icon) on the upper side of the panel.

Adding the Chat SDK with CocoaPods

CocoaPods is a dependency manager that lets you add third-party frameworks and libraries to projects.

Step 1 - Install CocoaPods

If not already done, install CocoaPods by running the following command in Terminal:

$ sudo gem install cocoapods

If you are on macOS and are having problems installing CocoaPods using gem, try using brew.

$ brew install cocoapods

See Getting started on the CocoaPods site.

Step 2 - Create a Podfile

A Podfile specifies the dependencies of an Xcode project. The file is simply named Podfile with no file extension.

To create a Podfile

1. In Terminal, navigate to the top-level folder of your project (the one with the xcodeproj file).

2. Create a Podfile with the following command:

   $ pod init

3. Open the file in Xcode with the following command:

   $ open -a Xcode Podfile

   The content should look as follows:

   # Uncomment the next line to define a global platform for your project
   # platform :ios, '9.0'
   
   target 'My Sample Chat App' do
       # Comment the next line if you don't want to use dynamic frameworks
       use_frameworks!
   
       # Pods for My Sample Chat App
   
   end

4. Add pod 'ZendeskChatSDK' to the do block:

   target 'My Sample Chat App' do
     ...
     pod 'ZendeskChatSDK'
   end

5. Save the Podfile.

Step 3 - Adding the SDK in your project

1. If you installed the 'ZendeskChatSDK' pod on your system for a previous version of Chat SDK v2, run the following command first:

   $ pod update ZendeskChatSDK

   CocoaPods updates the SDK pod on your system.

   Skip this step if you never added Chat SDK v2 with CocoaPods before.

2. Run the following command:

   $ pod install

   CocoaPods adds the latest version of the SDK to your project.

3. Close your project in Xcode, then reopen it by double-clicking the .xcworkspace file located in the project's root folder.

Important: Because your project now contains a dependency managed by CocoaPods, from now on you must open the project in Xcode by double-clicking the .xcworkspace file.

Running a test build

Before going any further, make sure you successfully added the Chat SDK to your project. One way is to run a test build. The application doesn't do much yet, but if you don't get any build errors you know you're on the right track.

You can use the Simulator app that’s included in Xcode to run your application. As the name implies, Simulator simulates running an iOS app on your Mac.

1. Make sure you opened the project by double-clicking the .xcworkspace file in the project's root folder (see Adding the Chat SDK with CocoaPods).

2. In the Scheme pop-up menu on the Xcode toolbar, choose iPhone 13 Pro Max.

   

3. Click the Run button (the play icon) on the left side of the Xcode toolbar.

   Xcode displays messages about the build process in the middle of the toolbar.

   Simulator starts automatically after the build is finished. Look for it on the Dock in macOS. Be patient. Simulator can take a while to get going the first time it starts. It's much faster with subsequent builds.

   Eventually your application opens in Simulator:

   

Consider the test a success if you don't get any build errors. You might get some build warnings but you can ignore them for now. If you want, you can click the tabs on the lower side to test that the basic tabbed interface works.

Initializing the Chat SDK

Before a user can use chat on their device, the application has to initialize the Chat SDK. The initialization process involves setting initial values and performing other setup tasks.

In this section, you'll update the sample application to initialize the Chat SDK dependencies and make them ready for use. The task consists of the following steps:

1. Getting the Zendesk Chat account key
2. Adding the initialization code to the application

Getting the Zendesk Chat account key

You'll need access to the Zendesk Chat dashboard to get the Chat account key. If you don't have access, ask somebody who does to perform the following steps.

1. In the Chat dashboard, click your profile icon in the upper right, then select Check Connection.

   

2. Copy and save the account key. It should be the second item in the list.

Adding the initialization code to the application delegate

You add the initialization code to the application delegate. Your application can delegate certain tasks to another object named appropriately enough the application delegate. The AppDelegate.swift file in your project defines this delegate. It contains a UIApplicationDelegate object with methods that run in response to important events in the lifetime of the application. For example, one method runs on application launch. You can add your own code to these event handlers.

1. In Xcode, select AppDelegate.swift in the Project navigator.

2. Add the following import statements after the import UIKit statement::

   import ChatSDK
   import ChatProvidersSDK

3. Add the the following initialization code to the application() method that has the didFinishLaunchingWithOptions argument. Make sure to paste the snippet before the return statement.

   Chat.initialize(accountKey: "your_account_key")

   Replace the your_account_key placeholder value with the account key you retrieved earlier from the Chat dashboard.

   The method should look as follows with the initialization code:

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   
       Chat.initialize(accountKey: "3NPBQia9qItVDD98qmCYEfVesWLR4IFC")
   
       return true
   }

   Applications are event driven, so you need to initialize the framework in an event handler like the application() method. The delegate method runs just before the application moves to the active state.

4. Save, then run a build to make sure you don't get any error messages.

Creating a navigation controller for the Chat interface

The Chat interface is designed to work with a navigation controller. A navigation controller manages a stack of views, each with its own view controller. Among other things, the controller provides a back button that lets users go back to the previous view in the stack.

Your sample project consists of a tab bar controller, a navigation controller, and one connected view controller:

In this section, you'll embed the view controller in a navigation controller so you can push the chat view atop the current view. The current view will show a button that customers can tap to chat with a support agent.

1. In the Project navigator, select the Main.storyboard file to open it in Interface Builder, Xcode's visual UI editor.

   The storyboard displays the application's views and their relationships:

   

   To get this bird's-eye view, right-click the storyboard and choose Zoom to Fit.

2. Zoom in on the view controller and click it to give it focus.

3. Select the round yellow icon on the view controller's top bar.

   

   The icon represents the view controller for the view.

4. In the Xcode menu, select Editor > Embed In > Navigation Controller.

   

5. Select the round yellow icon on the navigation controller's top bar.

6. In the Xcode menu, select Editor > Embed In > Tab Bar Controller.

   

   Tip: If your storyboard gets too congested, right-click and choose a zoom level.

Adding a button to start a chat

In this section, you'll add a button to the view controller that users can tap to start a chat with a support agent. This isn't a UI design tutorial so the changes are limited to adding a very basic button.

1. Select the Main.storyboard file to open it in Interface Builder.

2. Select View > Show Library to open the object library.

   The library lists objects you can add to the storyboard to build your user interface.

3. Scroll down the list until you find the Button object, then drag an instance to the view controller. Use the guidelines to position the button in the horizontal and vertical center of the view controller.

   

4. Double-click the button, change the text to Chat, and press Enter.

5. Select the button on the storyboard and change the font to Helvetica 24 in the Attributes inspector in the sidebar.

   

6. With the button still selected, click the Align button on the lower right side of the storyboard:

   

7. In the Add New Alignment Constraints dialog box, select the Horizontally in Container option, then click Add 1 Constraint.

8. With the button still selected, click the Add New Constraints button on the lower right side of the storyboard:

   

9. Make the following changes in the Add New Constraints dialog box:

   1. Click the T bar connecting the top-most neighbor so it turns solid red.

      

   2. Click Add 1 Constraint.

10. Save, then run a build to make sure you don't get any error messages.

Connecting the button

In this section, you connect your Chat button to a method in the view controller. The connection triggers the method, or action in iOS, when the user taps the Chat button. You'll later add code to the method that pushes the chat view on top of the current view.

Create an action

1. In the Project navigator, select ViewController.swift.

2. Delete everything in the ViewController subclass until it looks as follows:

   class ViewController: UIViewController {
   
   }

3. Add the following action to the subclass:

   @IBAction func pushChat(sender: AnyObject) {
   
   }

   Your code should look as follows:

   import UIKit
   
   class ViewController: UIViewController {
   
       @IBAction func pushChat(sender: AnyObject) {
   
       }
   
   }

   The expression @IBAction identifies the function as an Interface Builder (IB) action. You can call the function anything you want. I went with pushChat.

4. Save the file.

Connect the button to the action

1. Click the Main.storyboard file to switch to the storyboard.

2. Select the Chat button in your view controller by clicking it.

   The Chat button in the View Controller Scene in the document outline to the left of the storyboard (not the Project navigator) is highlighted.

3. While holding down the Control key or the right mouse button, drag the Chat button from the View Controller Scene to the view controller icon () on the view's top bar located in the storyboard, then release the key or mouse button to reveal a menu.

   

4. Select your newly created action under Sent Events (pushChatWithSender here).

5. Save the file, then run a build to make sure you don't get any error messages.

If everything checks out, you can initialize the Chat SDK and push the chat view atop the current view.

Pushing the chat view atop the current view

1. In the ViewController.swift file, add the following import statements after the import UIKit statement:

   import ChatSDK
   import MessagingSDK

2. Add the following statement to the pushChat() method you added earlier:

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

That's it. When the function runs in response to the user tapping your custom button, it builds the Chat view controller and pushes it atop the current view controller.

The completed ViewController.swift file should look as follows:

import UIKit
import ChatSDK
import MessagingSDK

class ViewController: UIViewController {

    @IBAction func pushChat(sender: AnyObject) {
        do {
          let chatEngine = try ChatEngine.engine()
          let viewController = try Messaging.instance.buildUI(engines: [chatEngine], configs: [])

          self.navigationController?.pushViewController(viewController, animated: true)
        } catch {
          // handle error
        }
    }

}

Start a chat

You can start a test chat if one or more chat agents are online. If nobody is online and you're a Zendesk Chat agent or administator, you can chat with yourself by setting your status to Online in the Chat dashboard:

Build and run the application in Simulator. Click your custom Chat button to view the chat interface. Enter a message and tap the send arrow to initiate a chat.

Next steps

At this point you should have a working iOS application that lets users chat with support agents. Put your project under git and create branches to try out different things. You can always reset if something goes wrong. See iOS Chat Getting Started for more information about configuring the Chat SDK and its dependencies.