LAST EDIT Jun 13 2024

The most common use case for client-level events is unread counts. Here's an example of a complete unread count integration for your chat app. As a first step we get the unread count when the user connects:

By default the UI component SDKs (React, React Native, ...) mark messages as read automatically when the channel is visible. You can also make the call manually like this:

While you're using the app, the unread count can change. A user can be added to a channel, a new message can be created, or the user can mark the messages as seen on another tab/device.

Unread counts are only stored and returned at connection time for channel members.

The markRead function can also be executed server-side by passing a user ID as shown in the example below:

It's also possible to mark an already read message as unread:

The mark unread operation can also be executed server-side by passing a user ID:

To support updating the unread count in real-time, you can listen to these events:

  • notification.message_new

  • notification.mark_read

  • notification.mark_unread

These two events include the fields total_unread_count and unread_channels. You can listen to them all at once like this:

Fetch Unread API


The unread endpoint can fetch unread counts server-side, eliminating the need to get this count on a client-side connection. This can be useful for including an unread count in notifications, or for gently polling when a user loads the application to keep the client up to date without loading up the entire chat.

A user_id whose unread count is fetched through this method automatically is counted as a Monthly Active User. This may affect your bill.

Batch Fetch Unread API


The batch unread endpoint works the same way as the non-batch version with the exception that it can handle multiple user IDs at once and that it is restricted to server-side only.

If a user ID is not returned in the response then the API couldnt find a user with that ID