Message Unread Count

The unread message count is a default feature provided by IMKit, which informs users of the number of unread messages in each conversation. Unread counts are displayed on conversation entries within the ConversationListFragment. Each conversation's unread count appears in the top-right corner of its icon. If the count exceeds 100, it displays as 99+.

tip

To use the unread message count feature, you must first build the conversation list page. IMKit does not implement a bottom navigation bar by default.

For versions prior to 5.10.0, there may be inaccuracies in unread counts. We recommend using version 5.10.0 or later.

Usage

The IMKit SDK has already implemented a complete set of logic for fetching and displaying unread message counts. When using the default conversation list and chat UI, no additional API calls are required.

IMKit automatically clears the unread count when users enter one-to-one chat, group chat, or system conversation pages. For multi-device login scenarios, IMKit synchronizes conversation read status across devices. You may disable this feature based on business needs. For details, see Multi-Device Read Status Sync.

Customization

If IMKit's default implementation doesn't meet your requirements, you can use relevant APIs from IMKit or IMLib SDKs.

Fetching Unread Counts

IMKit doesn't directly provide APIs for fetching unread counts. For custom requirements like the following, use IMLib SDK methods:

• Fetch all conversation unread counts (IMLib method)
• Fetch unread counts for specific conversations (IMLib method)
• Fetch unread counts by conversation type (IMLib method)

For core classes, APIs, and usage, refer to the IMLib documentation: Handling Unread Message Counts.

tip

IMLib methods don't provide page refresh capabilities. You'll need to implement custom notification mechanisms for page refreshes based on business requirements.

Clearing Unread Counts

Use IMCenter's clearMessagesUnreadStatus() method to clear all unread counts for a specified conversation. This method accepts a conversation type enum and a conversation ID. IMKit automatically refreshes the unread count display on the conversation list page.

Supported conversation types:

• One-to-one chat (ConversationType.PRIVATE)
• Group chat (ConversationType.GROUP)
• System (ConversationType.SYSTEM)

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation Id";

IMCenter.getInstance().clearMessagesUnreadStatus(conversationType, targetId, new ResultCallback<Boolean>() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {

    }
});

tip

• IMKit doesn't provide methods to clear unread counts by timestamp. You may use IMLib SDK methods (RongIMClient or RongCoreClient's clearMessagesUnreadStatus). Note that IMLib methods don't refresh pages automatically—implement custom notification mechanisms as needed.

Listening for Unread Count Changes

IMKit provides a listener mechanism for unread count changes. You can set up listeners to monitor unread count changes for one or more conversation types.

Versions 5.6.7 and Earlier

Use UnReadMessageManager's addObserver method to register an IUnReadMessageObserver, passing the conversation types to monitor. When unread counts change for monitored types, the SDK triggers onCountChanged, returning the total unread count via this listener.

UnReadMessageManager.getInstance().addObserver(conversationTypes,observer);

Unregister the listener when no longer needed:

UnReadMessageManager.getInstance().removeObserver(observer);

Versions 5.8.0 and Later

In version 5.8.0+, we introduced addForeverObserver and removeForeverObserve interfaces. These use strong references to ensure listener persistence. If used in Activity or Fragment, call removeForeverObserver when the component lifecycle ends to prevent memory leaks.

UnReadMessageManager.getInstance().addForeverObserver(conversationTypes, observer);

Unregister the listener when no longer needed:

UnReadMessageManager.getInstance().removeForeverObserver(observer);

Note: The addObserver and removeObserver interfaces in version 5.8.0+ use weak references to reduce memory leak risks.

Version 5.6.10

This version has an issue where UnReadMessageManager listeners may fail. We recommend upgrading to version 5.8.0 and following the interface guidelines.

Changing Read/Unread Icons to Text

By default, read messages in SDK chat UIs display a "checkmark" icon. To replace this with "Read" or "Unread" text, remove the default icon during message display.

Multi-Device Read Status Sync

tip

For SDK versions ≤ 5.6.2, multi-device sync of read/unread status is not supported for system conversations.

In IM scenarios, a single user account may log in across multiple devices. While RC synchronizes message data across devices when Multi-Device Message Synchronization is enabled, message read/unread status in conversations is stored locally per device.

IMKit SDK implements multi-device read status sync by default. When one device initiates sync, others receive notifications and sync read status accordingly. Enable/disable this feature based on business needs (enabled by default).

RongConfigCenter.conversationConfig().setEnableMultiDeviceSync(true);

Active Sync of Unread Status

IMKit SDK clears conversation unread status when entering chat UIs by default. To sync unread status without entering chat UIs, apps must actively sync.

IMCenter provides syncConversationReadStatus to notify other devices to sync a conversation's unread status during multi-device login. This method also clears local unread status for all messages before the specified timestamp. The conversation list page refreshes unread counts accordingly.

IMCenter.getInstance().syncConversationReadStatus(conversationType, targetId, timestamp, callback);

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID
timestamp	String	Timestamp of the last read message
callback	RongIMClient.OperationCallback	Callback interface

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation Id";
String timestamp = "12222222";

IMCenter.getInstance().syncConversationReadStatus(conversationType, targetId, timestamp, new RongIMClient.OperationCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {
    }
});

Listening for Read Status Sync Data

tip

IMKit's built-in conversation list page already implements unread status sync logic via this listener. When messages are marked as read on other devices, this listener clears corresponding unread counts locally—no additional handling is needed.

IMCenter provides the SyncConversationReadStatusListener. Clients must set this listener to receive read status sync data from other devices.

IMCenter.getInstance().addSyncConversationReadStatusListener(listener);

When receiving read status sync data, the listener triggers this method. The SDK marks all messages before or equal to the syncConversationReadStatus timestamp as read:

onSyncConversationReadStatus(Conversation.ConversationType type, String targetId)

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID

Unread Message Bubble Alerts

IMKit supports displaying unread message bubble alerts in chat UIs.

Displaying Unread Count Alerts

When a conversation's unread count exceeds 10, a reminder bubble (e.g., "99+") appears in the bottom-right corner upon entering the chat UI. Tapping this bubble jumps to the first unread message.

Unread count alerts are disabled by default. Enable them with:

// Enable unread count display
RongIM.getInstance().enableUnreadMessageIcon(true);
// Alternatively:
RongConfigCenter.conversationConfig().setShowHistoryMessageBar(true);

The bubble appears when unread messages exceed 10, showing "99+ new messages" if over 99. Customize the control in rc_conversation_fragment.xml (control ID: rc_new_message_number).

By default, the bubble appears when unread messages exceed 10. Configure this threshold:

RongConfigCenter.conversationConfig().setConversationShowUnreadMessageCount(10);

Displaying Unread Mention Alerts

When a group chat receives numerous messages (exceeding one screen) containing @mentions, entering the chat UI shows an unread @mention count in the top-right corner. Tapping this jumps to the earliest unread @mention, decrementing the count by 1. Subsequent taps adjust the count based on visible @mentions.

This feature is disabled by default. Enable it with:

// Enable unread @mention alerts
RongConfigCenter.conversationConfig().setShowNewMentionMessageBar(true);

Displaying New Message Alerts

When users view historical messages and the current view doesn't show the latest messages, new message alerts (e.g., "15 new messages") appear in the bottom-right corner. Tapping scrolls to the latest messages.

This feature is disabled by default. Enable it with:

// Enable new message alerts
RongIM.getInstance().enableNewComingMessageIcon(true);
// Alternatively:
RongConfigCenter.conversationConfig().setShowHistoryMessageBar(true);

The bubble appears for 1+ new messages, showing "99+" if over 99. Customize the control in layout/rc_fr_messagelist.xml.