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 |
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 |
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:
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:
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