This is the developer guide for Chat SDK v1. The new Chat SDK v2 for iOS is now available and is the recommended version to integrate Chat into your mobile app. It also removes the dependency on UIWebView which has been deprecated by Apple.

You can start a chat with or without configuring it. See Configuring a chat below.

Make sure to import ZDCChat before using starting or configuring a chat.

Objective-C

#import <ZDCChat/ZDCChat.h>

Swift

import ZDCChat

Before you can use the Chat SDK, you must initialize it with your account key:

Objective-C

[ZDCChat initializeWithAccountKey:@"your_account_key"];

Swift

ZDCChat.initialize(withAccountKey: "your_account_key")

Now the chat sdk is ready to be used.

You can present a chat modally from a view controller, or push it on a stack of view controllers in a navigation controller.

The examples in this section show how to start a chat with no configuration. If configuring the chat, replace nil in the examples with a configuration block. See Configuring a chat below.

Add the following statement to an action in a view controller in the navigation controller:

Objective-C

[ZDCChat startChatIn:self.navigationController withConfig:nil];

Swift

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

The statement pushes the chat view on top of the view controller.

Add the following statement to an event handler in a view controller:

Objective-C

[ZDCChat startChat:nil];

Swift

ZDCChat.start(nil)

Configuring a chat can include adding a pre-chat form, specifying a Zendesk Chat department to handle the chat, setting tags, or disabling the prompt that asks the user if they want to receive a chat transcript by email.

Use an instance of ZDCConfig to configure the chat.

Configures the chat configuration for the session, usually in the view controller that starts the chat. See Starting a chat above.

Objective-C

[ZDCChat startChatIn:self.navigationController withConfig:^(ZDCConfig *config) {
    config.department = @"Billing";
    config.tags = @[@"subscription", @"mobile_app"];
    config.preChatDataRequirements.email = ZDCPreChatDataRequired;
    config.emailTranscriptAction = ZDCEmailTranscriptActionNeverSend;
}];

Swift

ZDCChat.start(in: self.navigationController, withConfig: {config in
    config?.department = "Billing"
    config?.tags = ["subscription", "mobile_app"]
    config?.preChatDataRequirements.email = .required
    config?.emailTranscriptAction = .neverSend
})

where config is an inferred ZDCConfig object.

If starting the chat in a modal view, specify the configuration block as follows:

Objective-C

[ZDCChat startChat:^(ZDCConfig *config) {
    config.department = @"Billing";
    config.tags = @[@"subscription", @"mobile_app"];
    config.preChatDataRequirements.email = ZDCPreChatDataRequired;
    config.emailTranscriptAction = ZDCEmailTranscriptActionNeverSend;
}];

Swift

ZDCChat.start { config in
    config?.department = "Billing"
    config?.tags = ["subscription", "mobile_app"]
    config?.preChatDataRequirements.email = .required
    config?.emailTranscriptAction = .neverSend
}

The Chat SDK lets you display a pre-chat form before the user starts a chat. Any data entered by the user is saved in Zendesk Chat and associated with the user in subsequent chats.

The pre-chat form is configured with the preChatDataRequirements object, which is a member of the ZDCConfig class.

A pre-chat form is optional. It won't be displayed if you don't configure one.

Each property of the preChatDataRequirements object represents a field in the pre-chat form. A field won't be displayed if you don't set it.

Each field has the following attributes, expressed in the code as an enumeration.

Except for the message field, fields that you don't set as editable won't appear in subsequent chats as long as the user is on the same device. Zendesk Chat saves the form data and uses a device identifier to associate subsequent chats from the same device. The agent sees the data the user entered previously.

Setting a field as editable has the following effects:

When leaving an offline message, the user is always prompted for a name, email, and message. The pre-chat form settings are ignored.

You can configure the pre-chat form when the user starts a chat, using a ZDCConfig object. The form fields are ordered in the order of the statements in the configuration block.

Configuring the form when the user starts a chat:

Objective-C

[ZDCChat initializeWithAccountKey:@"your_account_key"];

[ZDCChat startChatIn:self.navigationController withConfig:^(ZDCConfig *config) {
    config.preChatDataRequirements.name = ZDCPreChatDataOptionalEditable;
    config.preChatDataRequirements.email = ZDCPreChatDataRequired;
    config.preChatDataRequirements.phone = ZDCPreChatDataOptional;
    config.preChatDataRequirements.department = ZDCPreChatDataOptionalEditable;
    config.preChatDataRequirements.message = ZDCPreChatDataRequired;
}];

Swift

ZDCChat.initialize(withAccountKey: "your_account_key")

ZDCChat.start(in: self.navigationController, withConfig: {config in
    config?.preChatDataRequirements.name = .optionalEditable
    config?.preChatDataRequirements.email = .required
    config?.preChatDataRequirements.phone = .optional
    config?.preChatDataRequirements.department = .optionalEditable
    config?.preChatDataRequirements.message = .required
})

where config is an inferred ZDCConfig object.

The Chat SDK lets you provide contact information about the user to the agent in Zendesk Chat. You can also let the user enter the information before the chat starts. See Providing a pre-chat form above.

The contact information is set with the ZDCVisitorInfo configuration object, which is then passed to the updateVisitor method of ZDCChat.

Note: The person using a mobile app is more commonly known as a user, not a visitor. However, the term visitor is used in the SDK to be consistent with the Zendesk Chat agent interface. Zendesk Chat uses visitor because Zendesk Chat chat has traditionally been embedded in web pages.

Objective-C

[ZDCChat updateVisitor:^(ZDCVisitorInfo *user) {
    user.phone = @"0123456789";
    user.name = @"Jane Doe";
    user.email = @"[email protected]";
}];

Swift

ZDCChat.updateVisitor { user in
    user?.phone = "0123456789"
    user?.name = "Jane Doe"
    user?.email = "[email protected]"
}

where user is an inferred ZDCVisitorInfo object.

You can set the contact information at any time. For example, you can set the information in the app delegate following the initialization code, or in the view controller that starts a chat.

Users can start a chat without any contact information. The user will be identified in the Zendesk Chat agent interface with an id such as Visitor 26119020. Zendesk Chat uses a device identifier to associate all subsequent chats from the same device with the same user.

If you set an email address and the Zendesk Support integration is enabled in your Zendesk Chat account, the ticket created in Zendesk Support when a chat ends will be linked to an existing user in Zendesk Support if the address matches the address of the user in Zendesk Support. Linking tickets to existing users ensures that agents in Zendesk Support see all the requests created by a particular user. It also gives your organization a more complete picture of its relationship with the user.

If you set the name, email, and phone values, the corresponding fields won't appear in the pre-chat form if the fields are required or optional, but will appear if they're editable. See Providing a pre-chat form above.

You can add a note to a chat when setting visitor info, by adding it to the ZDCVisitorInfo at creation time:

Objective-C

[ZDCChat updateVisitor:^(ZDCVisitorInfo *user) {
  user.phone = @"0123456789";
  user.name = @"Jane Doe";
  user.email = @"[email protected]";
  [user addNote:@"This is an Objective-C note"];
}];

Swift

ZDCChat.updateVisitor { user in
  user?.phone = "0123456789"
  user?.name = "Jane Doe"
  user?.email = "[email protected]"
  user?.addNote("This is a Swift note")
}

Providing user events to the chat agent can help the agent understand where the user has been in your application when the user starts a chat. The information also helps the agent understand what actions the user takes during a chat.

The event descriptions appear in the Visitor Path box in the agent's dashboard. Example:

To provide user events, add the following statement in relevant parts of your application:

Objective-C

[[ZDCChat instance].api trackEvent:@"Event description"];

Swift

ZDCChat.instance().api.trackEvent("Event description")

When deciding what events to track, consider the information that agents will find useful in assisting users. Provide relevant information, but not so much as to overwhelm the agent.

One example is instrumenting a login screen. In this example, you might track when:

• A user navigates to the login screen
• A user taps to log in
• Login fails, including a short reason/code
• Login succeeds

You wouldn't track when:

• A user taps the clear username or password field
• A user selects a text entry field

This is just a small example to give you some ideas. Tailor the events you decide to track to your app, business context, and support requirements.

Before ending a chat, the user is asked if they want to receive a transcript by email:

You can disable this default behavior by setting the emailTranscriptAction property of a ZDCConfig object as ZDCEmailTranscriptActionNeverSend.

Objective-C

[ZDCChat startChat:^(ZDCConfig *config) {
    config.emailTranscriptAction = ZDCEmailTranscriptActionNeverSend;
}];

Swift

ZDCChat.start { config in
    config?.emailTranscriptAction = .neverSend
}

To turn the prompt back on, specify ZDCEmailTranscriptActionPrompt (Objective-C) or ZDCEmailTranscriptAction.Prompt (Swift) when starting the chat.

Users can send attachments while chatting. You can enable or disable this feature in the Zendesk Chat agent interface. For instructions, see Managing file sending in Zendesk Chat in the Zendesk Chat Help Center. If you don't have access to the agent interface, ask somebody who does to complete the task for you.

iOS 10 requires NSPhotoLibraryUsageDescription and NSCameraUsageDescription to be set in your application info.plist. This key specifies the reason for your app to access the user’s photo library and camera. See NSPhotoLibraryUsageDescription in the Apple docs.

A session lasts 1 hour if you configured push notifications or 5 minutes if not.

The chat session will terminate after any of the following conditions:

• There's no activity on the chat for the duration of the session (1 hour or 5 minutes)
• The visitor has been disconnected for the duration of the session
• The agent ends the chat, at which point the session disconnect timeout is reset to 5 minutes
• The visitor ends the chat, at which time the session immediately terminates