Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Unread Message Count Persistence and Conversation Loading in Agora Chat UIKit v2.x

Updated

Issue Description:

Users integrating Agora Chat UIKit v2.x into a React web application experienced issues with unread message counts and historical message persistence. Specifically, unread counts reset to zero after a page reload or navigation, and previously unread messages did not appear in the unread count or conversation list upon reloading.

 

Platform/SDK:

  • Platform: Web (React 18.3.1)
  • Agora SDK: agora-chat-uikit v2.0.0, agora-chat v1.3.1
  • Browser: All major browsers

 

Error Message (optional):

No explicit error message appears in the console, but the chat store data (rootStore.conversationStore.conversationList) does not populate correctly after reloading or reconnecting.

 

Step by Step Solution:

1. Confirm UIKit Version:

Ensure your project uses Agora Chat UIKit v2.x. Some methods and hooks differ between versions 1.x and 2.x.

 

2. Initialize Client Before Loading Conversations:

Call client.open() with valid user credentials before rendering the UIKit components. This ensures correct initialization of the Chat SDK session.

javascript
const client = ChatUIKit.useClient();
await client.open({ user: userAgoraId, accessToken: userToken });

 

3. Load Conversations After Connection:

The client.open() method does not automatically load all past conversations with unread message counts. After the connection is established, explicitly call:

javascript
const conversations = await client.getConversationList();

Then, update your custom state provider or the store with the result to display conversation data and unread counts.

 

4. Implement Persistent Conversation Data:

The conversationList inside rootStore.conversationStore is temporary and does not persist across reloads.

  • Store the conversations in your local storage or a state management solution (e.g., Redux) as part of your app state.
  • On page reload or app startup, fetch stored data and then sync with the latest unread message counts from the server.

 

5. Manually Calculate and Update Unread Counts:

Aggregate unread counts across all conversations after fetching them:

javascript
const totalUnread = conversations.reduce((total, conv) = total + (conv.unreadCount || 0), 0);

Update this count in your global state or badge display components.

 

6. Track Real-Time Changes:

Subscribe to message and conversation update events to keep unread counts accurate:

  • Use event handlers such as onTextMessage and onConversationChange.
  • Ensure event subscriptions are reattached after reconnecting the client.

 

7. Reload Historical Messages on Start:

If unread messages were received while the user was offline, use the message retrieval API:

javascript
const messages = await client.getHistoryMessages({ conversationId, pageSize: 20 });

Display these messages accordingly in the conversation view.

 

Root Cause:

Unread message counts and conversation data were resetting because Agora Chat UIKit v2.x does not automatically persist unread counts or reload full conversation data upon browser refresh or reconnection. Developers must explicitly fetch this information when the client reconnects.

 

Prevention/Best Practice:

  • Always trigger a manual fetch of conversations using client.getConversationList() after client.open() to restore state.
  • Use an application-level store (Redux or Context API) to persist unread count information between reloads.
  • Re-initialize event handlers after each reconnection to maintain real-time updates.
  • Regularly synchronize with the server to ensure unread counts remain accurate, especially when multiple browser tabs or sessions are active.

 

Corresponding Document/Link (optional):

Related articles