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 Android provides an event listener ZendeskEventListener where you can listen for any ZendeskEvent emitted from the SDK.

Available Events

ZendeskEvent is a sealed class with a subclass for each event that can currently be emitted. It has the following events:

• UnreadMessageCountChanged
• AuthenticationFailed
• FieldValidationFailed
• ConnectionStatusChanged
• SendMessageFailed
• ConversationAdded
• ConversationStarted
• ConversationOpened
• MessagesShown
• ProactiveMessageDisplayed
• ProactiveMessageClicked
• ConversationWithAgentRequested
• ConversationWithAgentAssigned

UnreadMessageCountChanged

The number of unread messages has changed.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	String	Yes	The Unix timestamp of the event
data	ConversationUnreadCountChange	Yes	Shows the change in total unread messages and the change in unread messages for a conversation
currentUnreadCount	Int	Yes	The current number of unread messages. This is deprecated, use data instead

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

FieldValidationFailed

Invoked when validation checks fails for conversation fields.

Name	Type	Mandatory	Comment
errors	List	Yes	Details about errors that occurred

ConnectionStatusChanged

Invoked when The SDK [ConnectionStatus] has changed due to an action or another event.

Name	Type	Mandatory	Comment
connectionStatus	ConnectionStatus	Yes	A representation of the current connection status of the SDK

SendMessageFailed

Invoked when a message fails to be sent.

Name	Type	Mandatory	Comment
cause	Throwable	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

ConversationStarted

Invoked when a user starts a conversation on this device. The user can initiate it by clicking the new conversation button, receiving and clicking on a proactive message, or creating a default conversation.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
conversationId	String	Yes	The id of the conversation that was started
timestamp	Long	Yes	The Unix timestamp of the event

ConversationOpened

Invoked when the user opens a conversation.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
conversationId	String	Yes	The id of the conversation that was opened
timestamp	Long	Yes	The Unix timestamp of the event

MessagesShown

Invoked whenever the messages shown to the user are updated.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
conversationId	String	Yes	The id of the conversation that the messages belong to
timestamp	Long	Yes	The Unix timestamp of the event
messages	List	Yes	The list of messages that are displayed

ProactiveMessageDisplayed

Invoked when a proactive message is successfully displayed.

Warning: Notification permission should be granted for this event to be emitted.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ProactiveMessageDisplayedDetails	Yes	The ids of the proactive message and campaign

ProactiveMessageClicked

Invoked when a proactive message (notification) is clicked by the user.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ProactiveMessageClickedDetails	Yes	The ids of the proactive message and campaign

ConversationWithAgentRequested

Invoked when a user starts waiting for an agent to join the conversation.

Note: The event won’t be emitted if the wait time is disabled, as well as in cases where the wait time is not shown.

For more information about these cases, see Displaying wait time estimates in messaging conversations.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ConversationWithAgentRequestedDetails	Yes	The ids of the conversation

ConversationWithAgentAssigned

Triggered when an agent is assigned to the conversation. This event occurs only if the user is actively viewing the conversation screen or the image viewer. If the user is on a different screen, the event will not be triggered.

Note: The event won’t be emitted if the wait time is disabled, as well as in cases where the wait time is not shown.

For more information about these cases, see Displaying wait time estimates in messaging conversations.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ConversationWithAgentAssignedDetails	Yes	The ids of the conversation

ConversationServedByAgent

Triggered when the agent types the first message to the conversation. This events occurs if the user is actively viewing the conversation or the conversation list screen.

Note: The event won’t be emitted if the wait time is disabled, as well as in cases where the wait time is not shown.

For more information about these cases, see Displaying wait time estimates in messaging conversations.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ConversationServedByAgentDetails	Yes	The id of the conversation and agent details

ConversationExtensionOpened

This event is triggered when a conversation extension view opens, either by the end user tapping an action button or through an automatic trigger.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ConversationExtensionOpenedDetails	Yes	The id of the conversation and URL of the conversation extension

ConversationExtensionDisplayed

This event is triggered when a conversation extension view is displayed, either as a result of a user click or an automatic action.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ConversationExtensionDisplayed	Yes	The id of the conversation and URL of the conversation extension

ArticleBrowserClicked

This event is triggered when an article opens in an external browser (for example, restricted articles).

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ArticleBrowserClickedDetails	Yes	The URL of the article

ArticleClicked

This event is triggered when an article is opened in the article viewer.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	ArticleBrowserClickedDetails	Yes	The ids of the article and conversation

MessagingOpened

This event is triggered when the messaging SDK is opened by the end user.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event

MessagingClosed

This event is triggered when the messaging SDK is closed by the end user.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event

NewConversationButtonClicked

This event is triggered when the new conversation button is clicked by the user.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	NewConversationButtonClickedData	Yes	The source of the conversation

PostbackButtonClicked

This event is triggered when a postback button is clicked in a message.

Name	Type	Mandatory	Comment
id	String	Yes	The id of the event
timestamp	Long	Yes	The Unix timestamp of the event
data	PostbackButtonClickedDetails	Yes	The conversation id and action name

EventListener

The EventListener can be created and attached to the current Zendesk instance using zendesk.addEventListener. To avoid missing events, make sure the Zendesk instance is fully initialized and valid before adding the listener.

A reliable approach is to call zendesk.addEventListener within the successCallback of the Zendesk.initialize method. This ensures the listener is added to the most current SDK instance.

You can find an example of this implementation within our demo apps:

• Unread message demo app
• JWT demo app

Kotlin

Here is a code sample showing how the event listener can be used, added and removed:

// To create and use the event listener:
val zendeskEventListener: ZendeskEventListener = ZendeskEventListener {
    zendeskEvent -> when (zendeskEvent) {
        is ZendeskEvent.UnreadMessageCountChanged -> {
            // Your custom action...
        }
        is ZendeskEvent.AuthenticationFailed -> {
            // Your custom action...
        }
        is ZendeskEvent.FieldValidationFailed -> {
            // Your custom action...
        }
        else -> {
           // Default branch for forward compatibility with Zendesk SDK and its `ZendeskEvent` expansion
        }
    }
}

// To add the event listener to your Zendesk instance:
// (safe for concurrent use)
zendesk.addEventListener(zendeskEventListener)

// To remove the event listener from your Zendesk instance:
// (safe for concurrent use)
zendesk.removeEventListener(zendeskEventListener)

Java

Below is a code sample showing how the event listener can be used, added and removed.

This includes the ZendeskEventListenerAdapter, an implementation of the ZendeskEventListener designed to provide better support for Java:

// To create and use the event listener:
ZendeskEventListener zendeskEventListener =
    new ZendeskEventListener() {
        @Override
        public void onEvent(@NonNull ZendeskEvent zendeskEvent) {
            if (zendeskEvent instanceof UnreadMessageCountChanged) {
                // Your custom action...
            } else if (zendeskEvent instanceof AuthenticationFailed) {
                // Your custom action...
            } else if (zendeskEvent instanceof FieldValidationFailed) {
                // Your custom action...
            }
        }
    };

// Or using the ZendeskEventListenerAdapter:
ZendeskEventListenerAdapter listenerAdapter = new ZendeskEventListenerAdapter() {
    @Override
    public void onUnreadMessageCountChanged(@NonNull UnreadMessageCountChanged event) {
        super.onUnreadMessageCountChanged(event);
        // Your custom action
    }
};

// To add the event listener to your Zendesk instance:
zendesk.addEventListener(zendeskEventListener);

// To remove the event listener from your Zendesk instance:
zendesk.removeEventListener(zendeskEventListener);

EventFlow

Below is a code sample which shows the usage of the zendesk.eventFlow API:

lifecycleScope.launch {
    zendesk.eventFlow.collect { zendeskEvent ->
        when (zendeskEvent) {
            is ZendeskEvent.UnreadMessageCountChanged -> {
                // Your custom action
            }
            else -> Unit
        }
    }
}