Customizing the look

This page shows you how to customize the SDK UI.

Before you start

Before you start, you should know the following:

• You can customize only one color that is used in the Unified SDK UI.
• The navigation bar color is not set by the Unified SDK but inherited from the presenting navigation controller or the UINavigationBar appearance singleton.
• You cannot move UI elements, remove parts of the UI, or add new parts.

If customizing the UI elements is important to you, consider using the Chat providers and building your own UI.

Customizing the Chat experience

The Chat SDK provides the ChatConfiguration class that you can use to enable or disable certain conversational features.

Swift

let chatConfiguration = ChatConfiguration()
chatConfiguration.isAgentAvailabilityEnabled = false

Objective-C

ZDKChatConfiguration *chatConfiguration = [[ZDKChatConfiguration alloc] init];
chatConfiguration.isAgentAvailabilityEnabled = YES;

Flag	Description
chatMenuActions	An array of ChatMenuAction items which configures the menu items available to your users. Default is [.emailTranscript, .endChat] which shows both the "Request transcript" and "End chat" menu items. An empty array will hide the menu.
isChatTranscriptPromptEnabled	If true, visitors will be prompted at the end of their chat asking them whether they would like a transcript sent by email.
isPreChatFormEnabled	If true, visitors are prompted for information in a conversational manner prior to starting the chat. Defaults to true.
isOfflineFormEnabled	If this flag is enabled (as well as isAgentAvailabilityEnabled) then visitors will be presented with a form allowing them to leave a message if no agents are available. This will create a support ticket. Defaults to true.
preChatFormFieldConfiguration	This property allows you to configure the requirements of each of the pre-chat form fields. See Configuring a pre-chat form for more information.
isAgentAvailabilityEnabled	If true, and no agents are available to serve the visitor, they will be presented with a message letting them know that no agents are available. If it's disabled, visitors will remain in a queue waiting for an agent. Defaults to true. Only checks the availability of the account, not specific departments. If availability information is needed on the department level, see Getting the availability of agents.

For the full documentation on the ChatConfiguration class, see the reference docs.

Configuring a pre-chat form

A pre-chat form is presented to a user before the chat starts with an agent, providing an opportunity for information to be gathered. The form can support name, email address, and phone number fields as well as selecting a department and entering an initial message. A local bot presents the form to the user in a conversational flow. The bot details can be changed to match your brand. See Configuring the chat bot for more details.

The pre-chat form is enabled by default. It can be disabled by setting the isPreChatFormEnabled flag to false. Form fields can be configured with one of the following levels of requirements:

State	Description
.optional	User can continue without filling the field.
.hidden	Field will not be shown to the user.
.required	User is required to fill the field to continue.

To configure the requirements of each of the pre-chat form fields, use the ChatFormConfiguration class.

Swift

let formConfiguration = ChatFormConfiguration(name: .required,
                                              email: .optional,
                                              phoneNumber: .hidden,
                                              department: .required)
let chatConfiguration = ChatConfiguration()
chatConfiguration.isPreChatFormEnabled = true
chatConfiguration.preChatFormConfiguration = formConfiguration

Objective-C

ZDKChatFormConfiguration *formConfiguration = [[ZDKChatFormConfiguration alloc] initWithName:ZDKFormFieldStatusRequired
                                                                                       email:ZDKFormFieldStatusOptional
                                                                                 phoneNumber:ZDKFormFieldStatusHidden
                                                                                  department:ZDKFormFieldStatusRequired];
ZDKChatConfiguration *chatConfiguration = [[ZDKChatConfiguration alloc] init];
chatConfiguration.isPreChatFormEnabled = YES;
chatConfiguration.preChatFormConfiguration = formConfiguration;

Pre-chat form and the ChatAPIConfiguration class

The pre-chat form checks the details set on the Chat.instance.configuration object. You can use the ChatAPIConfiguration class to preset the user's info and a department for a chat session. If a property on the visitorInfo object is populated, then the respective pre-chat form field will be hidden, regardless of its FormFieldStatus. The same rule applies for the department property. If all visitorInfo properties and the department are populated, then the form will not show and the user can send a message to start a chat.

Make sure to handle these properties appropriately when setting and resetting an identity.

Enabling multi-line quick replies

It's possible that your Chat instance has a long list of departments with long names. This can lead to a poor user experience when a user is selecting their desired department in the pre-chat form. If this is the case, you can leverage a Flexbox-style layout. You can switch to this layout by enabling the isMultilineResponseOptionsEnabled flag on the MessagingConfiguration. See the documentation for more details.

Swift

let configuration = MessagingConfiguration()
configuration.isMultilineResponseOptionsEnabled = true

Objective-C

ZDKClassicMessagingConfiguration *configuration = [[ZDKClassicMessagingConfiguration alloc] init];
configuration.isMultilineResponseOptionsEnabled = YES;

### Styling the chat screen

There is currently only one colour that can be set on the Chat SDK. This colour is used to style the user's message bubbles. For more details, see the docs on styling the Unified SDK.

Swift

import CommonUISDK // import the necessary component
CommonTheme.currentTheme.primaryColor = .red

Objective-C

#import <CommonUISDK/CommonUISDK.h> // import the necessary component
[ZDKCommonTheme currentTheme].primaryColor = [UIColor redColor];

Configuring the Chat bot

The Chat SDK leverages the Unified SDK to present chat features to the user in a conversational flow. Pre-chat forms and offline forms are sent to the user via a scripted interaction named "Answer Bot" by default. Customer satisfaction requests are also sent by Answer Bot, but only when requested by the agent. This is not the Answer Bot SDK, but it makes the interaction consistent across all the SDKs. The name and icon of the bot can be overwritten to promote your brand. For more details, see the docs on the Messaging configuration as well as this article on the difference between this feature and the Answer Bot.

Note: Zendesk has renamed our bot capabilities. Answer Bot is now Zendesk bots. For more information on this change, see this announcement.

Localizing the text

The Chat SDK is localized in 33 different languages including right-to-left languages. It is possible to override the strings to match your brand. See Localizing the UI for more details.