Chat API

This document covers how to create your own Chat UI using the Chat API. It covers sending and receiving data to and from Zendesk Chat, managing a chat lifecycle, and registering to receive notifications for certain events. It doesn't cover how to render the data.

You can find out more about using NSNotificationCenter to listen for events in Apple's API documentation, NSNotificationCenter Class.

Sample apps

We also have some sample apps on Github which demonstrate how to use the Zendesk mobile SDKs in different ways. These can serve as useful references when integrating with the API providers.

Starting a chat session

To start a chat session:

Objective-C

// With default configurations
[[ZDCChatAPI instance] startChatWithAccountKey:accountKey];

// Or with configurations
[[ZDCChatAPI instance] startChatWithAccountKey:accountKey config:config];

Swift

// With default configurations
ZDCChatAPI.instance().startChat(withAccountKey: accountKey)

// Or with configurations
ZDCChatAPI.instance().startChat(withAccountKey: accountKey, config: config)

This starts the session, connecting with the config provided (or default if one is not provided). Calling startChatWithAccountKey starts a new chat or resumes a chat session if there is one in progress.

Events

The Chat SDK API emits six types of events:

Type Description
Connection events Chat connection status has been updated
Timeout events Indicates when a session times out
Chat log events A new chat event. These are the events that ultimately get rendered
Agent events The agent information has changed. Primarily used as an indicator that the agent is typing
Upload events Indicates upload progression and status
Account events Account has gone on / offline
Connection events

Connection events indicate a chat connection state has changed. A chat must be in the connected state to send messages. Messages are not cached to send when the chat connects. You can configure chat anytime as this information is cached.

Listening for connection events

Once a session has been initiated, listen for connection status updates:

Objective-C

[[ZDCChatAPI instance] addObserver:self forConnectionEvents:@selector(connectionStateUpdated)];

// and remember to remove the observer before deallocation
[[ZDCChatAPI instance] removeObserverForConnectionEvents:self];

Swift

ZDCChatAPI.instance().addObserver(self, forConnectionEvents: #selector(onConnectionStateUpdated))

// and remember to remove the observer before deallocation
ZDCChatAPI.instance().removeObserver(forConnectionEvents: self)
Handling connection events

When you receive a notification that the connection status has changed, you can obtain the new status with the following code:

Objective-C

ZDCConnectionStatus status = [[ZDCChatAPI instance] connectionStatus];

Swift

let status = ZDCChatAPI.instance().connectionStatus

Where ZDCConnectionStatus is:

Type Description
ZDCConnectionStatusUninitialized Chat connection has not been started
ZDCConnectionStatusConnecting Chat is currently establishing a connection
ZDCConnectionStatusConnected Chat is connected
ZDCConnectionStatusClosed Chat connection has been closed
ZDCConnectionStatusDisconnected Chat connection lost
ZDCConnectionStatusNoConnection Device has no internet connection

When the chat has connected you can begin to send messages.

Timeout events

It is important to listen for timeout events as well as connection events. When a chat times out, it moves to the uninitialized state and a timeout notification is sent.

Listening for timeout events

To listen for timeout events:

Objective-C

[[ZDCChatAPI instance] addObserver:self forTimeoutEvents:@selector(timeoutEvent)];


// and remember to remove the observer before deallocation
[[ZDCChatAPI instance] removeObserverForTimeoutEvents(self)];

Swift

ZDCChatAPI.instance().addObserver(self, forTimeoutEvents: #selector(self.timeoutEvent(_:)))

// and remember to remove the observer before deallocation
ZDCChatAPI.instance().removeObserver(forTimeoutEvents: self)
Handling timeout events

When a chat times out, you won't be able to send messages. The chat returns to the uninitialized state. You can start a new chat or inform the user the chat has ended but you cannot reconnect to the timed out chat.

Chat log events

Chat log events contain the majority of the information you will present to the user. An effective chat UI must be able to render chat log events and send messages.

Listening for chat log events

To listen for chat log events:

Objective-C

[[ZDCChatAPI instance] addObserver:self forChatLogEvents:@selector(chatEvent:)];

// and remember to remove the observers before object deallocation
[[ZDCChatAPI instance] removeObserverForChatLogEvents:self];

Swift

ZDCChatAPI.instance().addObserver(self, forChatLogEvents: #selector(chatEvent(_:)))

// and remember to remove the observers before object deallocation
ZDCChatAPI.instance().removeObserver(forChatLogEvents: self)
Handling chat log events

There are a number of different types of chat events:

Type Description
ZDCChatEventTypeMemberJoin Member (agent) joined the chat
ZDCChatEventTypeMemberLeave Member (agent) left the chat
ZDCChatEventTypeSystemMessage Chat system message event notifying of visitors in the queue
ZDCChatEventTypeTriggerMessage Chat message generated by a trigger
ZDCChatEventTypeAgentMessage Chat message from an agent
ZDCChatEventTypeVisitorMessage Chat message from the visitor
ZDCChatEventTypeVisitorUpload Visitor file upload
ZDCChatEventTypeAgentUpload Agent file upload
ZDCChatEventTypeRating Chat rating
ZDCChatEventTypeRatingComment Chat rating comment

Chat events contain nearly all the information that you're likely to display in the chat UI.

Property Description
eventId The events unique Id in this session
timestamp Timestamp for the event
nickname Event author's nickname in the system
displayName Event author's display name
message Chat message (may be nil depending on the type of event)
type Event type
verified Indicates whether this event has been confirmed by the server or is a local notification
visitorQueue Number of visitors in the queue for events of type ZDCChatEventTypeSystemMessage
firstMessage True if this is the first message by the author
leadMessage True if this is the first message by the author since another presentable event occurred (avatar should be shown)
options NSMutableArray
selectedOptionIndex The index of the option that the user has selected (optional)
fileUpload If this event represents a file upload in the active session this will contain the upload object
attachment The attachment for this event if one exists
rating Visitor rating of the current chat

The complete header for ZDCChatEvent can be found on GitHub

When a chat log event is received, you can get the event object as follows:

Objective-C

NSArray *events = [[ZDCChatAPI instance] livechatLog];
ZDCChatEvent *event = [events lastObject];

Swift

let events = ZDCChatAPI.instance().livechatLog
let event = events?.last

Due to the way events are created, there is no need to update your UI with outgoing messages. You can simply handle a stream of incoming events and render them appropriately based on their type.

When you send a message or upload a file, an event is created immediately. It is then sent to Zendesk Chat. When Zendesk Chat receives the event, it is updated and verified is set to true.

Events are uniquely identified by eventId. Subsequent events with the same eventId are updates to the initial event. An example would be a VisitorUpload. Multiple events are received to indicate changes in upload status.

Agent events

Agent events are posted whenever the agent information changes. Typically this is when an agent joins or leaves the chat, or when an agent starts or stops typing.

Listening for agent events

To listen for agent events:

Objective-c

[[ZDCChatAPI instance] addObserver:self forAgentEvents:@selector(agentEvent:)];

//Don't forget to unregister
[[ZDCChatAPI instance] removeObserverForAgentEvents:self];

Swift

ZDCChatAPI.instance().addObserver(self, forAgentEvents: #selector(onAgentEvent))

//Don't forget to unregister
ZDCChatAPI.instance().removeObserverForAgentEvents(forAgentEvents: self)
Handling agent events

An agent event notification tells you that agent info has been updated.

Property Type Description
agentId NSString Agent Id (nickname)
displayName NSString Agent display name
title NSString Agent title
avatarURL NSString URL of the agents avatar, may be nil
typing BOOL True if the agent is currently typing in this conversation

You can get a list of all the agents currently in a chat using:

Objective-C

NSDictionary *agents = [[ZDCChatAPI instance] agents];

Swift

let agents = ZDCChatAPI.instance().agents
Upload events

Upload events are used to indicate the status and progress of file uploads.

Registering for upload events

To listen for upload event notifications:

Objective-c

[[ZDCChatAPI instance] addObserver:self forUploadEvents:@selector(uploadEvent:)];

//Don't forget to unregister
[[ZDCChatAPI instance] removeObserverForUploadEvents:self];

Swift

ZDCChatAPI.instance().addObserver(self, forUploadEvents: #selector(self.chatUploadEvent(_:)))

//Don't forget to unregister
ZDCChatAPI.instance().removeObserver(forUploadEvents: self)
Handling upload events

The notification contains a ZDCChatUpload object. As upload events only provide a ZDCChatUpload object they need to be linked to their corresponding chat log event fileUpload property.

File uploads also generate regular chat log events that contain upload status information. Handling upload events is only needed if you want to display upload progress.

Objective-c

ZDCChatUpload* file = notification.object;

Swift

let attachment = note.object as? ZDCChatUpload
Account events

Account events indicate when your Zendesk Chat account goes online or offline -- that is, there are no longer any agents online.

Registering for account events

To listen for account event notifications:

Objective-c

[[ZDCChatAPI instance] addObserver:self forAccountEvents:@selector(accountEvent:)];

//Don't forget to unregister
[[ZDCChatAPI instance] removeObserverForAccountEvents:self];

Swift

ZDCChatAPI.instance().addObserver(self, forAccountEvents: #selector(self.accountEvent(_:)))

//Don't forget to unregister
ZDCChatAPI.instance().removeObserver(forAccountEvents: self)
Handling account events

To get the status of your Zendesk Chat account:

Objective-c

[ZDCChatAPI instance].isAccountOnline;

Swift

ZDCChatAPI.instance().isAccountOnline

Sending a message

To send a chat message:

Objective-C

[[ZDCChatAPI instance] sendChatMessage:@"A message"];

Swift

ZDCChatAPI.instance().sendChatMessage("A message")

Only send a chat message once a connection has been fully established.

Ending a chat

To end a chat, which closes all connections and discards all session data:

Objective-C

[[ZDCChatAPI instance] endChat];

Swift

ZDCChatAPI.instance().endChat()

Note that this does not immediately cause a session to end, but instead notifies the server that it should take steps to end the session. Attempts to start a new chat immediately after calling endChat will result in the previous chat resuming.

Listing departments

To list online departments:

Objective-C

[[ZDCChatAPI instance] departments];

Swift 3

ZDCChatAPI.instance().departments

You must be connected to a Chat Session.