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.
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:
// With default configurations [[ZDCChatAPI instance] startChatWithAccountKey:accountKey]; // Or with configurations [[ZDCChatAPI instance] startChatWithAccountKey:accountKey config:config];
// 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.
The Chat SDK API emits six types of events:
|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 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:
[[ZDCChatAPI instance] addObserver:self forConnectionEvents:@selector(connectionStateUpdated)]; // and remember to remove the observer before deallocation [[ZDCChatAPI instance] removeObserverForConnectionEvents:self];
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:
ZDCConnectionStatus status = [[ZDCChatAPI instance] connectionStatus];
let status = ZDCChatAPI.instance().connectionStatus
Where ZDCConnectionStatus is:
||Chat connection has not been started|
||Chat is currently establishing a connection|
||Chat is connected|
||Chat connection has been closed|
||Chat connection lost|
||Device has no internet connection|
When the chat has connected you can begin to send messages.
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:
[[ZDCChatAPI instance] addObserver:self forTimeoutEvents:@selector(timeoutEvent)]; // and remember to remove the observer before deallocation [[ZDCChatAPI instance] removeObserverForTimeoutEvents(self)];
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:
[[ZDCChatAPI instance] addObserver:self forChatLogEvents:@selector(chatEvent:)]; // and remember to remove the observers before object deallocation [[ZDCChatAPI instance] removeObserverForChatLogEvents:self];
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:
||Member (agent) joined the chat|
||Member (agent) left the chat|
||Chat system message event notifying of visitors in the queue|
||Chat message generated by a trigger|
||Chat message from an agent|
||Chat message from the visitor|
||Visitor file upload|
||Agent file upload|
||Chat rating comment|
Chat events contain nearly all the information that you're likely to display in the chat UI.
||The events unique Id in this session|
||Timestamp for the event|
||Event author's nickname in the system|
||Event author's display name|
||Chat message (may be nil depending on the type of event)|
||Indicates whether this event has been confirmed by the server or is a local notification|
||Number of visitors in the queue for events of type ZDCChatEventTypeSystemMessage|
||True if this is the first message by the author|
||True if this is the first message by the author since another presentable event occurred (avatar should be shown)|
||The index of the option that the user has selected (optional)|
||If this event represents a file upload in the active session this will contain the upload object|
||The attachment for this event if one exists|
||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:
NSArray *events = [[ZDCChatAPI instance] livechatLog]; ZDCChatEvent *event = [events lastObject];
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 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:
[[ZDCChatAPI instance] addObserver:self forAgentEvents:@selector(agentEvent:)]; //Don't forget to unregister [[ZDCChatAPI instance] removeObserverForAgentEvents:self];
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.
||NSString||Agent Id (nickname)|
||NSString||Agent display name|
||NSString||URL of the agents avatar, may be nil|
||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:
NSDictionary *agents = [[ZDCChatAPI instance] agents];
let agents = ZDCChatAPI.instance().agents
Upload events are used to indicate the status and progress of file uploads.
Registering for upload events
To listen for upload event notifications:
[[ZDCChatAPI instance] addObserver:self forUploadEvents:@selector(uploadEvent:)]; //Don't forget to unregister [[ZDCChatAPI instance] removeObserverForUploadEvents:self];
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.
ZDCChatUpload* file = notification.object;
let attachment = note.object as? ZDCChatUpload
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:
[[ZDCChatAPI instance] addObserver:self forAccountEvents:@selector(accountEvent:)]; //Don't forget to unregister [[ZDCChatAPI instance] removeObserverForAccountEvents:self];
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:
Sending a message
To send a chat message:
[[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:
[[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.
To list online departments:
[[ZDCChatAPI instance] departments];
You must be connected to a Chat Session.