Styling your chat UI

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.

The presentation of most elements of the chat UI is defined by iOS UIAppearance attributes. The objects that can be styled, along with their default styles, are listed below:

Objective-C

// loading the chat
[[ZDCLoadingView appearance] set...]
[[ZDCLoadingErrorView appearance] set...]

// pre-chat form
[[ZDCPreChatFormView appearance] set...]
[[ZDCFormCell appearance] set...]

// offline message view
[[ZDCOfflineMessageView appearance] set...]

// chat view
[[ZDCChatView appearance] set...]
[[ZDCTextEntryView appearance] set...]
[[ZDCJoinLeaveCell appearance] set...]
[[ZDCSystemTriggerCell appearance] set...]
[[ZDCVisitorChatCell appearance] set...]
[[ZDCAgentChatCell appearance] set...]
[[ZDCChatTimedOutCell appearance] set...]
[[ZDCRatingCell appearance] set...]
[[ZDCAgentAttachmentCell appearance] set...]
[[ZDCVisitorAttachmentCell appearance] set...]

// chat UI and nav buttons
[[ZDCChatUI appearance] set...]

// chat overlay icon
[[ZDCChatOverlay appearance] set...]

// agent chat avatar
[[ZDCChatAvatar appearance] set...]

Swift

// loading the chat
ZDCLoadingView.appearance()...
ZDCLoadingErrorView.appearance()...

// pre-chat form
ZDCPreChatFormView.appearance()...
ZDCFormCell.appearance()...

// offline message view
ZDCOfflineMessageView.appearance()...

// chat view
ZDCChatView.appearance()...
ZDCTextEntryView.appearance()...
ZDCJoinLeaveCell.appearance()...
ZDCSystemTriggerCell.appearance()...
ZDCVisitorChatCell.appearance()...
ZDCAgentChatCell.appearance()...
ZDCChatTimedOutCell.appearance()...
ZDCRatingCell.appearance()...
ZDCAgentAttachmentCell.appearance()...
ZDCVisitorAttachmentCell.appearance()...

// chat UI and nav buttons
ZDCChatUI.appearance()...

// chat overlay icon
ZDCChatOverlay.appearance()...

// agent chat avatar
ZDCChatAvatar.appearance()...

Hint: In Swift, the compiler needs a hint about what type of view you are modifying, store the cell as a local property to get access to its properties.

Example:

let visitorCell = ZDCVisitorChatCell.appearance()
visitorCell.bubbleColor = .red
visitorCell.textColor = .white
let agentCell = ZDCAgentChatCell.appearance()
...

This will give you access to the properties via Xcode's autocomplete functionality. The cast can be removed once all desired properties are discovered.

You'll find full Objective-C examples of the available appearance attributes and their default values in the ZopimChatSample > ChatStyling.m class.

iOS 13 and Dark Mode support

We currently don't support iOS 13 Dark Mode. However, you can handle Dark Mode using the following UIAppearance attributes.

let background = ZDCChatView.appearance()
let visitor = ZDCVisitorChatCell.appearance()
let agent = ZDCAgentChatCell.appearance()
let inputFieldStyle = ZDCTextEntryView.appearance()

if #available(iOS 13.0, *) {
    ZDCChat.instance()?.chatViewController?.view.backgroundColor = .systemBackground
    background.chatBackgroundColor = .systemBackground
    visitor.bubbleColor = .systemBlue
    visitor.textColor = .label
    agent.bubbleColor = .systemRed
    agent.textColor = .label

    inputFieldStyle.areaBackgroundColor = .systemBackground
    inputFieldStyle.textEntryBackgroundColor = .secondarySystemBackground
    inputFieldStyle.textEntryColor = .label
    // ...
} else {
    // default unspecified styling
}

Hiding the chat overlay

To hide the chat overlay, set its setEnabled property to false:

Objective-C

[[[ZDCChat instance] overlay] setEnabled:NO];

Swift

ZDCChat.instance().overlay.setEnabled(false)

Strings and localization

The provided strings can be changed easily with XCode. In your project, right-click the strings file in the bundle and select Open As > ASCII Property List.

Note that some system messages sent by Zendesk Chat are not controlled by the SDK, and so cannot be edited. Any string not documented on this page cannot be edited.

To provide your own strings, create a new ZDCChatStrings.bundle to use in your app and provide strings for the following keys:

"ios.ZDCChat.agentJoined"
"ios.ZDCChat.agentLeft"
"ios.ZDCChat.backButton"
"ios.ZDCChat.cancel"
"ios.ZDCChat.cancelButton"
"ios.ZDCChat.cantConnectMessage"
"ios.ZDCChat.cantConnectTitle"
"ios.ZDCChat.chat.startingChatMessage"
"ios.ZDCChat.chatConnectionLost.message"
"ios.ZDCChat.chatConnectionLost.title"
"ios.ZDCChat.chatEndedMessage"
"ios.ZDCChat.chatEndedTitle"
"ios.ZDCChat.chatTextEntry.placeholderText"
"ios.ZDCChat.chatTextEntry.sendButton"
"ios.ZDCChat.done"
"ios.ZDCChat.download.failedMessage"
"ios.ZDCChat.end"
"ios.ZDCChat.endButton"
"ios.ZDCChat.network.connectionError"
"ios.ZDCChat.nextButton"
"ios.ZDCChat.no"
"ios.ZDCChat.noAgentsButton"
"ios.ZDCChat.noAgentsMessage"
"ios.ZDCChat.noAgentsTitle"
"ios.ZDCChat.noConnectionMessage"
"ios.ZDCChat.noConnectionTitle"
"ios.ZDCChat.offlineMessageFailed.message"
"ios.ZDCChat.preChatForm.departmentPlaceholder"
"ios.ZDCChat.preChatForm.emailPlaceholder"
"ios.ZDCChat.preChatForm.messagePlaceholder"
"ios.ZDCChat.preChatForm.namePlaceholder"
"ios.ZDCChat.preChatForm.phonePlaceholder"
"ios.ZDCChat.preChatForm.required"
"ios.ZDCChat.preChatForm.requiredTemplate"
"ios.ZDCChat.pushChatEndedBody"
"ios.ZDCChat.pushChatEndedTitle"
"ios.ZDCChat.rating.comment.placeholder"
"ios.ZDCChat.rating.comment.title"
"ios.ZDCChat.rating.commentButton"
"ios.ZDCChat.rating.editButton"
"ios.ZDCChat.rating.title"
"ios.ZDCChat.reconnecting"
"ios.ZDCChat.retry"
"ios.ZDCChat.sendOfflineMessageError.message"
"ios.ZDCChat.sendOfflineMessageError.sendButton"
"ios.ZDCChat.sendOfflineMessageError.title"
"ios.ZDCChat.timeoutMessage"
"ios.ZDCChat.title"
"ios.ZDCChat.transcriptEmailAlert.dontSendButton"
"ios.ZDCChat.transcriptEmailAlert.emailPlaceholder"
"ios.ZDCChat.transcriptEmailAlert.message"
"ios.ZDCChat.transcriptEmailAlert.sendButton"
"ios.ZDCChat.transcriptEmailAlert.title"
"ios.ZDCChat.unsentMessage"
"ios.ZDCChat.upload.error.access"
"ios.ZDCChat.upload.error.size"
"ios.ZDCChat.upload.error.type"
"ios.ZDCChat.upload.source.camera"
"ios.ZDCChat.upload.source.gallery"
"ios.ZDCChat.visitorQueue"
"ios.ZDCChat.yes" = "Yes";
"ios.ZDCChat.ok" = "Ok";