Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Manage local conversations

Updated

Introduces how to use the Agora Chat SDK to implement managing local messages functionalities.

In chat apps, a conversation is composed of all the messages in a peer-to-peer chat, chat group, or chatroom. The Chat SDK supports managing messages by conversations, including retrieving and managing unread messages, deleting the historical messages on the local device, and searching historical messages.

This page introduces how to use the Chat SDK to implement these functionalities.

This feature supports Chrome, Firefox, Safari, and other browsers that use these engines (for example, Microsoft Edge). It does not support Internet Explorer.

Understand the tech

The Chat SDK allows you to implement the following functions in your project by calling APIs:

  • getLocalConversations: Get the local conversation list
  • getLocalConversation: Get a single local conversation
  • setLocalConversationCustomField: Set conversation custom fields
  • clearConversationUnreadCount: Clear the number of unread messages in the conversation
  • removeLocalConversation: Delete a single local conversation
  • getServerConversations: Synchronize the server conversation list to the local database

Prerequisites

Before proceeding, take the following steps:

  • Import the Web SDK files as required

    1. Install the SDK using npm, yarn, or another package management tool

      # npm
npm install agora-chat

# yarn
yarn add agora-chat

    2. Import the SDK and required modules

      Introduce the corresponding functional modules according to project requirements. For example, introduce the user relationship module:

      import MiniCore from "agora-chat/miniCore/miniCore";
import * as contactPlugin from "agora-chat/contact/contact";

    3. Register the module to miniCore

      Register the imported function module into miniCore:

      const miniCore = new MiniCore({
  appKey: "your appKey",
});

// "contact" Fixed value
miniCore.usePlugin(contactPlugin, "contact");

    4. Use registered modules

      After registering the required modules, you can use the functions provided by these modules in your project:

      // Get contact list
miniCore.contact.getContacts();

  • Integrate the plugin

    If local conversation storage is supported, you need to integrate the local storage plugin. The sample code is as follows:

    import MiniCore from "agora-chat/miniCore/miniCore";
import * as contactPlugin from "agora-chat/contact/contact";
import * as localCachePlugin from "agora-chat/localCache/localCache";

const miniCore = new MiniCore({
  appKey: "your appKey",
});
// Use the contact plugin, "contact" is a fixed value.
miniCore.usePlugin(contactPlugin, "contact");
// Use the local storage plugin, "localCache" is a fixed value.
miniCore.usePlugin(localCachePlugin, "localCache");

// Log in to Chat
miniCore.open({
  username: "userId",
  accessToken: "accessToken",
});

Implementation

This section shows how to implement managing messages.

The structure of the conversation object is as follows:

interface ConversationItem {
  // Conversation ID.
  conversationId: string;
  // Conversation type: single chat and group chat are `singleChat` and `groupChat` respectively.
  conversationType: ConversationType;
  // The number of unread messages in the conversation.
  unReadCount?: number;
  // The latest message.
  lastMessage?: LocalMessageBody;
  // Conversation custom fields.
  customField?: Record;
}

Retrieve conversations

You can call the getLocalConversations method to get a list of all local conversations at once. After obtaining the conversations, the SDK returns the list in the reverse order of the conversation active time (the timestamp of the latest message). The conversation list data is a `` structure.

The sample code is as follows:

miniCore.localCache.getLocalConversations().then((res) => {
  // Obtain local conversation list successfully.
  console.log(res);
});

Retrieve a local conversation

You can call the getLocalConversation method to obtain a single local conversation object. The sample code is as follows:

const options = {
  // Conversation type: single chat and group chat are `singleChat` and `groupChat` respectively.
  conversationType: "singleChat",
  // Conversation ID.
  conversationId: "conversationId",
};

miniCore.localCache.getLocalConversation(options).then((res) => {
  // Obtained local conversation successfully.
  console.log(res);
});

Set conversation custom fields

You can call the setLocalConversationCustomField method to set the custom field of the local conversation, that is, pass in the key-value object, where key is the field name and value is the field value.

The sample code is as follows:

const options = {
  // Conversation type: single chat and group chat are `singleChat` and `groupChat` respectively.
  conversationType: "singleChat",
  // Conversation ID.
  conversationId: "conversationId",
  // Conversation custom fields.
  customField: { custom: "custom" },
};

miniCore.localCache.setLocalConversationCustomField(options).then(() => {
  // Set conversation custom fields successfully.
});

Clear the number of unread messages in a conversation

You can call the clearConversationUnreadCount method to clear the number of unread messages in a single local conversation. The sample code is as follows:

const options = {
  // Conversation type: single chat and group chat are `singleChat` and `groupChat` respectively.
  conversationType: "singleChat",
  // Conversation ID.
  conversationId: "conversationId",
};

miniCore.localCache.clearConversationUnreadCount(options).then(() => {
  // Successfully cleared the number of unread messages for the specified conversation.
});

Delete a conversation

You can call the removeLocalConversation method to delete a single local conversation. The sample code is as follows:

const options = {
  // Conversation type: single chat and group chat are `singleChat` and `groupChat` respectively.
  conversationType: "singleChat",
  // Conversation ID.
  conversationId: "conversationId",
  // Whether to delete local messages, the default value is `true`.
  isRemoveLocalMessage: true,
};

miniCore.localCache.removeLocalConversation(options).then(() => {
  // Deleted local conversation successfully.
});

Clear chat history

To clear the current user's chat history, including messages and conversations in individual chats, group chats, and chat rooms, you can call the deleteAllMessagesAndConversations method. Note that clearing the chat history on the server means that you will not be able to retrieve conversations and messages from the server, although other users will not be affected.

chatClient.deleteAllMessagesAndConversations().then(() => {
  // Cleared all conversation and message records successfully
});

Synchronize server conversation list to local

You can call the getServerConversations method to get the server conversation list and synchronize it to the local database. The sample code is as follows:

const options = {
  /** The expected number of conversations per page. The value range is [1,50], and the default is `20`. */
  pageSize: 20,
  /** The cursor position to start getting data. If an empty string ('') is passed, the SDK starts to obtain the conversations from the latest active conversation. */
  cursor: "",
};
miniCore.contact.getServerConversations(options).then((res) => {
  // Obtain the server conversation list and synchronize the local successfully.
  console.log(res);
});

Import the Web SDK files as required

If you want to minimize the SDK size, you can import the SDK files as required.

FunctionFile for importUsage
Contact and messageimport \* as contactPlugin from "agora-chat/contact/contact";miniCore.usePlugin(contactPlugin, "contact");
Groupimport \* as groupPlugin from "agora-chat/group/group";miniCore.usePlugin(groupPlugin, "group");
Chat roomimport \* as chatroomPlugin from "agora-chat/chatroom/chatroom";miniCore.usePlugin(chatroomPlugin, "chatroom");
Threadimport \* as threadPlugin from "agora-chat/thread/thread";miniCore.usePlugin(threadPlugin, "thread");
Translationimport \* as translationPlugin from "agora-chat/translation/translation";miniCore.usePlugin(translationPlugin, "translation");
Presenceimport \* as presencePlugin from "agora-chat/presence/presence";miniCore.usePlugin(presencePlugin, "presence");

The sample code is as follows:


const miniCore = new MiniCore({
  appKey: "your appKey",
});

// The fixed value "contact" is used here.
miniCore.usePlugin(contactPlugin, "contact");

// Get the contact list.
miniCore.contact.getContacts();

// Add the listener.
miniCore.addEventHandler("handlerId", {
  onTextMessage: (message) => {},
});

// Login
miniCore.open({
  username: "username",
  accessToken: "accessToken",
});

Next steps

After implementing managing messages, you can refer to the following documents to add more messaging functionalities to your app:

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved