Skip to main content
Use channel unread count when your app needs inbox badges, mention indicators, or total chat unread state. The SDK exposes unread state on channel models and provides an aggregate total for channels known to the current user.

Platform Surface

Parameters

Read Channel Unread State

Read unread count and mention state from the channel object. If the platform exposes a support flag, check it before showing unread count for channel types that do not support markers.

Observe Total Channel Unread

Use total unread APIs for app-level badges or global chat navigation. The aggregate contains the unread count and whether any unread message mentions the current user.
The total unread count is calculated from the channels the SDK has already synced into its local cache. It is a live observation, not a one-time server fetch, so it starts at 0 and only reflects an accurate total after the channel list has been queried at least once. To show a total unread badge before the chat list screen appears, fetch the channel list first (for example, run a channel query in the background) so the SDK has the data to calculate from, then observe the total unread count.

Implementation Notes

Model Source

Per-channel values come from channel or subchannel models, so update the UI from SDK observations instead of maintaining a separate unread counter.

Cache-Based Total

Total channel unread is derived from locally synced channels. Fetch the channel list at least once before the count reflects an accurate total.

Mention Priority

Use isMentioned to visually prioritize channels where the current user has unread mentions.

Subchannel Mode

When your app uses subchannels directly, read subchannel unread fields from the subchannel model where the platform exposes them.

Read Marking

Mark messages as read from the message model to update unread state.

Message Read Status

Mark messages as read.

Message Receipt Sync

Subscribe to receipt topics while a chat screen is open.

Message Preview

Show latest-message previews beside unread badges.