Starting and configuring a chat

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

Initializing the chat

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.

Starting a chat

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.

Starting a chat in a navigation controller

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.

Starting a chat in a modal view

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

Objective-C

[ZDCChat startChat:nil];

Swift

ZDCChat.start(nil)

Configuring a chat

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.

ZDCConfig

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

Properties
Property Description
preChatDataRequirements Configures the pre-chat form. See Providing a pre-chat form
department The department to be selected when a chat starts. If this is non-nil, the specified department must be online. Otherwise, the user is prompted to leave a message.
tags The tags to be set when a chat starts
emailTranscriptAction Mail transcript action after the chat ends. The default is to ask the user if they want a transcript. See Disabling transcripts
visitorPathOne String placed in the first line of the Visitor Path in the Zendesk Chat agent interface. Equivalent to the 'referrer'. Default format: "{app_name}, v{app_version}({build_number})"
visitorPathTwo String placed in the second line of the Visitor Path in the Zendesk Chat agent interface. Equivalent to the 'title'. Default format: "{app_name}"
connectionTimeout Timeout applied on initial chat startup; if the session does not achieve a connection in this time then the connection attempt is considered to have failed (default 30 seconds).
reconnectionTimeout Timeout applied when reconnecting to an existing active chat, if the session does not achieve a connection in this time then the connection attempt is considered to have failed and the user is asked if they want to continue or not (default 120 seconds).
Example

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
}

Providing a pre-chat form

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.

Form fields

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.

Field Description
name A text field that lets the user enter their name
email A text field that lets the user enter their email address
phone A text field that lets the user enter their phone number
message A text field that lets the user enter the first message before starting the chat
department A list of departments with the message "What can we help you with?" that lets the user route the chat. You must add departments in Zendesk Chat first. See Creating agents and departments in the Zendesk Chat Help Center
Form field attributes

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

Attribute Description
Not Required Uses the data if known, but won't display the field if not known
Optional If not known, displays the field, but the information is not required to start a chat
Required If not known, displays the field and the user must provide the information before they can start a chat
Optional Editable Same as Optional, except known information is displayed in the field so the user can edit it
Required Editable Same as Required, except known information is displayed in the field so the user can edit it

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:

Editable field Effect
name, email, or phone An editable text field with the value entered previously (or provided by the visitor object) is displayed when the user starts the next chat
department The list is displayed when the user starts the next chat, but the department the user selected in the previous chat won't be preselected. The user can still choose another department
message No effect. The field is always empty when the user starts a new chat

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

Examples

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.

Displaying the user's contact information

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.

ZDCVisitorInfo properties
Property Description
name The user's name
email The user's email address
phone The user's phone number
Example

Objective-C

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

Swift

ZDCChat.updateVisitor { user in
    user?.phone = "0123456789"
    user?.name = "Jane Doe"
    user?.email = "jdoe@example.com"
}

where user is an inferred ZDCVisitorInfo object.

Discussion

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.

Adding a note to a chat

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 = @"jdoe@example.com";
  [user addNote:@"This is an Objective-C note"];
}];

Swift

ZDCChat.updateVisitor { user in
  user?.phone = "0123456789"
  user?.name = "Jane Doe"
  user?.email = "jdoe@example.com"
  user?.addNote("This is a Swift note")
}

Providing user events

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:

breadcrumbs

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")
Discussion

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.

Disabling transcripts

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

image

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

Example

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.

Disabling attachments

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.

Attachments and Camera Usage on iOS 10

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.

Session duration

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

  • There has been no activity on the chat for 1 hour, or
  • The visitor has been disconnected for an hour, or
  • 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