Unread Messages

Tracking unread messages in your app enhances user engagement by providing timely notifications.

How it works

• The SDK can call an action event when the unread count changes with the updated unread message count.
• You can get the total number of unread messages for the end user using the GetUnreadMessageCountAsync() API.

Get unread message count

The following snippet shows how to retrieve the unread message count:

2.2.1 and below:

UnreadCountResult unreadMessageCountResult = await ZendeskSdk.Instance.Messaging.GetUnreadMessageCountAsync();

2.3.0 and up: Optional parameters:

• onUnreadCountChanged: (Action) Action to be called when the unread count changes
• shouldSubscribe: (boolean) Whether to subscribe to the websocket event outside of conversation
• cancellationToken (Added after 4.3.0): A cancellation token to cancel the operation. Defaults to CancellationToken.None.

The GetUnreadMessageCountAsync method returns an object of type UnreadCountResult, which includes an IsSuccess property indicating whether the operation succeeded. If the operation fails, you can examine the Error property, an enum of type UnreadCountError, to understand the cause of the failure.

4.4.0 and up: When you call GetUnreadMessageCountAsync with shouldSubscribe: true (the default) while the SDK is disconnected, the SDK now fetches an authoritative count from the server before reopening the realtime connection. This ensures live updates start from a current count rather than a stale cached value. This refresh:

• Applies only to JWT-authenticated sessions.
• Is rate limited to at most one server fetch every 60 seconds per process. Calls made during the cooldown are served from the cached count.
• Fails safely, so any network error, cancellation, or throttled request leaves the cached count untouched and never throws.

The cache-only path (shouldSubscribe: false) is unchanged and never triggers a server fetch. The onUnreadCountChanged callback also now always reports the total across all of the end user's conversations, so the value stays consistent no matter which conversation changed.

Refresh the count after the UI closes

While the messaging UI is open, the SDK keeps the unread count up to date over its realtime connection. Closing the UI tears that connection down, so to refresh the badge afterwards you re-call GetUnreadMessageCountAsync.

4.4.0 and up: You can register an OnUiClosed callback when initializing the SDK. It runs once the SDK UI has fully closed and its realtime connection has been torn down, which is the right moment to refresh the badge. Because it fires only once teardown is complete, calling GetUnreadMessageCountAsync from the callback reliably fetches a fresh count and re-subscribes for live updates instead of racing an in-progress teardown.

OnUiClosed is a parameterless Action. You get the count from the API, so the callback does not need to carry it. It fires for any full UI close, including Guide.

var initialisation = await ZendeskSdk.InitializeAsync(options =>
{
    options.ChannelId = channelId;
    options.OnUiClosed = RefreshUnreadBadge;
});

async void RefreshUnreadBadge()
{
    UnreadCountResult result = await ZendeskSdk.Instance.Messaging.GetUnreadMessageCountAsync(
        onUnreadCountChanged: SetUnreadBadge);

    if (result.IsSuccess)
    {
        SetUnreadBadge(result.UnreadCount);
    }
}

If you don't track the unread count you don't need to register OnUiClosed. Closing the UI still tears the connection down cleanly.