Tracking with Zendesk events

Introduction

Zendesk events provide a way for your app to listen for important changes and actions within the Zendesk SDK. These events allow you to track user engagement, monitor support flows, and respond to key moments in the customer journey.

Why use Zendesk events?

• Analytics: Integrate Zendesk events with your analytics platform (for example, Firebase, Mixpanel, Amplitude) to track metrics such as unread message counts, authentication failures, or conversation lifecycle events. This helps you understand user behavior, measure support effectiveness, and optimize your in-app support experience.
• Logging & Monitoring: Use events to log errors, field validation issues, or connection status changes for debugging and monitoring. This enables you to proactively detect issues and improve reliability.

Common use cases

Here are some practical ways you can use Zendesk events in your app:

• Track when a user receives or reads a new message (for badge counts or engagement metrics).
• Log authentication failures to monitor for integration issues.
• Monitor when conversations are started, opened, or closed to analyze support flow.
• Integrate with crash reporting or monitoring tools to capture SDK errors and user actions.

The Zendesk SDK for iOS provides an event observer where you can listen for any ZendeskEvent emitted from the SDK.

You can find a demo app demonstrating the capability in our Zendesk SDK Demo app on GitHub.

Available events

ZendeskEvent is a non-frozen enum with a case for each event that can currently be emitted. It has the following cases:

• unreadMessageCountChanged
• сonversationUnreadCountChanged
• authenticationFailed
• conversationAdded
• connectionStatusChanged
• sendMessageFailed
• conversationOpened
• conversationStarted
• messagesShown

unreadMessageCountChanged

Invoked when there is a change to the current total number of unread messages.

Note: unreadMessageCountChange is deprecated. Use сonversationUnreadCountChanged instead.

Name	Type	Mandatory	Comment
currentUnreadCount	Int	Yes	The current total number of unread messages.

сonversationUnreadCountChanged

Invoked when the number of unread messages has changed

Name	Type	Mandatory	Comment
id	UUID	Yes	The unique identifier of the event.
timestamp	Date	Yes	The timestamp of the event.
data	ConversationUnreadCountChange	Yes	Displays the change in the total number of unread messages and the change in unread messages for a specific conversation.

authenticationFailed

Invoked when an authentication error has occurred on any of the API calls.

Name	Type	Mandatory	Comment
error	Error	Yes	Details about the error that occurred.

conversationAdded

Invoked when a conversation has been added.

Name	Type	Mandatory	Comment
conversationId	String	Yes	The id of the conversation that was added.

connectionStatusChanged

The SDK ZendeskConnectionStatus has changed due to an action or another event.

Name	Type	Mandatory	Comment
connectionStatus	Enum	Yes	The recently developed ZendeskConnectionStatus.

sendMessageFailed

Invoked when a message fails to be sent.

Name	Type	Mandatory	Comment
error	Error	Yes	Details about the error that occurred.

conversationOpened

Invoked when the conversation screen is opened.

Name	Type	Mandatory	Comment
id	UUID	Yes	The id of the event.
timestamp	Date	Yes	The timestamp of the event.
conversationId	String	No	The id of the conversation that was opened (optional).

conversationStarted

Invoked when the conversation screen is opened.

Name	Type	Mandatory	Comment
id	UUID	Yes	The id of the event.
timestamp	Date	Yes	The timestamp of the event.
conversationId	String	Yes	The id of the conversation that was started.

messagesShown

Invoked when the messages shown to the user are updated.

Name	Type	Mandatory	Comment
id	UUID	Yes	The id of the event.
timestamp	Date	Yes	The timestamp of the event.
conversationId	String	Yes	The id of the conversation that was started.
messages	[ZendeskMessage]	Yes	An array of messages that are displayed in the conversation.

EventObserver

Swift

Below is a code sample showing how the event observer can be added and removed. The enum is non-frozen so additional cases may be added in the future.

Include a "catch-all" case @unknown default to match any value and produce a warning if all known enum cases are not matched. If additional cases are added and you do not wish to see a warning here, remove the @unknown attribute. See the snippet below:

// To add an event observer to your Zendesk instance:
Zendesk.instance?.addEventObserver(self) { event in
    switch event {
    case .unreadMessageCountChanged(let unreadCount):
        // Your custom action...
    case .authenticationFailed(let error as NSError):
        print("Authentication error received: \(error)")
        print("Domain: \(error.domain)")
        print("Error code: \(error.code)")
        print("Localized Description: \(error.localizedDescription)")
        // ...
    case .conversationAdded(conversationId: let conversationId):
        print("Conversation with the conversation id \(conversationId) was successfully created")
    case .connectionStatusChanged(connectionStatus: let connectionStatus):
        print("connectionStatusChanged event emitted: \(connectionStatus.stringValue)")
    case .sendMessageFailed(let error as NSError):
        print("Authentication error received: \(error)")
        print("Domain: \(error.domain)")
        print("Error code: \(error.code)")
        print("Localized Description: \(error.localizedDescription)")
        // ...
    @unknown default:
        break
    }
}

// To remove an event observer from your Zendesk instance:
Zendesk.instance?.removeEventObserver(self)

Objective-C

Below is a code sample showing how the event observer can be added and removed.

Each case in ZDKZendeskEvent is prefixed with ZDKZendeskEvent in the following format:

ZDKZendeskEvent{EventName}

There is currently only one case to match against, but since the enum is non-frozen, there may be additional cases added in the future. For this reason, add a "catch-all" case default that matches any value.

// Get your Zendesk instance:
Zendesk *instance = [Zendesk instance];

// To add an event observer to your Zendesk instance:
[instance addEventObserver:self :^(enum ZDKZendeskEvent event, id _Nullable value) {
    switch (event) {
    case ZDKZendeskEventUnreadMessageCountChanged:
        // Your custom action...
    case ZDKZendeskEventAuthenticationFailed:
        // Your custom action...
    default:
        break;
    }
}];

// To remove an event observer from your Zendesk instance:
[instance removeEventObserver:self];