DocumentationAPI Reference

Getting Started

Getting Started

In addition to a Zendesk Talk subscription, the SDK has the following requirements:

  • Minimum iOS version: 12.0

Talk SDK 3.0.0 and newer is built with Xcode 14.2+ and Swift 5.7.2.

Prerequisites

Obtaining the initialization details

You need the following information to initialize the Talk SDK:

  • The URL of your Zendesk Support instance
  • Your app's id in Zendesk Support
  • The client id of your app in Zendesk Support

These details are found on the Channels page in Admin Center.

If you have access to Admin Center, sign in and go to Channels > Classic > Mobile SDK. If you don't have admin access, ask a Zendesk admin to get the information for you.

Integrating the Talk SDK

Follow these steps to integrate the Talk SDK in your app:

  1. Add the Talk SDK to your project
  2. Initialize the SDK
  3. Set an anonymous identity
  4. Create a Talk SDK instance
  5. Check for agent availability
  6. Make a call

The code snippets on this page show a simple, light-touch integration using the built-in UI that comes with the SDK. You can decide to use the API and build your own UI. Alternatively, you can use the built-in UI and customize its look. For more details, see Using the SDK with your own UI or Customizing the look.

Adding the Talk SDK to your project

You can add the Talk SDK to your project using either CocoaPods or Carthage dependancy managers. If you prefer, you also can manually add the Talk SDK to your project. For details, see Adding the Talk SDK.

Update usage descriptions in Info.plist

The Talk SDK requires microphone access for making a voice call. The app must describe a purpose for requesting this permission and present it to the user in the access request.

If your app doesn't already request permissions for these features, update your Info.plist file with a usage description for NSMicrophoneUsageDescription.

Learn more about Cocoa keys in the Apple developer documentation.

Initializing the SDK

Initialize the SDK in the app's AppDelegate when the application is launched.

  1. Import the following frameworks into the AppDelegate file in your project:

    Swift

    import ZendeskCoreSDKimport TalkSDK

    Objective-C

    #import <ZendeskCoreSDK/ZendeskCoreSDK.h>#import <TalkSDK/TalkSDK.h>

  2. Paste the following initialization code into the application:didFinishLaunchingWithOptions: method of AppDelegate:

    Swift

    Zendesk.initialize(appId: "appId", clientId: "clientId", zendeskUrl: "url")

    Objective-C

    [ZDKZendesk initializeWithAppId:"appId" clientId:"clientId" zendeskUrl:"url"];

  3. Replace the parameter placeholders with your initialization details.

Setting an anonymous identity

To set an anonymous identity, add the following statement before any interaction with the SDK. We recommend putting it just after the Zendesk.initialize(appId:clientId:zendeskUrl:) call.

Swift

let identity = Identity.createAnonymous()Zendesk.instance?.setIdentity(identity)

Objective-C

id<ZDKObjCIdentity> userIdentity = [[ZDKObjCAnonymous alloc] initWithName:nil email:nil];[[ZDKZendesk instance] setIdentity:userIdentity];

See How anonymous identities work in the mobile SDKs for more information about the lifecycle of an anonymous identity.

Providing additional user context

Setting the user email and name will improve the user experience of your customer by providing user context to your agent.

Swift

let identity = Identity.createAnonymous(name: "End User", email: "[email protected]")Zendesk.instance?.setIdentity(identity)

Objective-C

id<ZDKObjCIdentity> userIdentity = [[ZDKObjCAnonymous alloc] initWithName:@"End User" email:@"[email protected]"];[[ZDKZendesk instance] setIdentity:userIdentity];

Note: Unlike other Zendesk SDKs, JWT authentication is not supported in the Talk SDK. Attempting to use JWT authentication will result in failures. JWT authentication will be included in a future release.

Creating a Talk SDK instance

To use the Talk SDK API, you need to create an instance of the SDK first. Create the instance after the SDK is initialized and the anonymous identity is set.

Swift

let talk = Talk(zendesk: Zendesk.instance!)

Objective-C

ZDKTalk *talk = [[ZDKTalk alloc] initWithZendesk:[ZDKZendesk instance]];

We recommend storing the created Talk instance in a property with the lifetime scoped relative to the envisioned usage of the SDK features within your application. Example: Create the instance on entering the settings from where the call to a support agent can be made.

Checking for agent availability

Use the lineStatus(digitalLine:completion:) method to determine if any agents are available for the Talk digital line. Hiding the call button when no agents are available is recommended to improve the user experience.

Swift

talk.lineStatus(digitalLine: "digitalLineNickname") { [weak self] result in    let isAgentAvailable: Bool
    switch result {    case .success(let lineStatus):        isAgentAvailable = lineStatus.agentAvailable    case .failure:        isAgentAvailable = false    }
    self?.callBarButtonItem.isEnabled = isAgentAvailable}

Objective-C

__weak typeof(self) weakSelf = self;[talk lineStatusWithDigitalLine: @"digitalLineNickname" completion: ^(id<LineStatus> _Nullable lineStatus, NSError * _Nullable error) {    BOOL isAgentAvailable = NO;
    if (lineStatus != nil) {        isAgentAvailable= lineStatus.agentAvailable;    }
    weakSelf.callButton.enabled = isAgentAvailable;}];

Making a call

The Talk SDK provides a built-in UI flow for checking the required permissions and calling an agent. You can run it with the following statement:

Swift

talk.startCall(to: "digitalLineNickname")

Objective-C

[talk startCallToDigitalLine: @"digitalLineNickname"];

The SDK checks for microphone permissions and whether or not the digital line requires recording consent. The presented view lets the user grant the permissions and give the consent if required. After completing this step, or if no input from user was required, the call screen is presented and the call is connected.

Need more than the out-of-the box UI?

To customize the look of the built-in permission screen or call screen, see Customizing the look.

If you need something completely different and prefer to build and use your own permission or call screens, see Using the SDK with your own UI.