# Manage local conversations (/en/realtime-media/im/build/build-core-messaging/messages/manage-messages/web)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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.

    <CalloutContainer type="success">
      <CalloutDescription>
        This feature supports Chrome, Firefox, Safari, and other browsers that use
        these engines (for example, Microsoft Edge). It does not support Internet
        Explorer.
      </CalloutDescription>
    </CalloutContainer>

    ## Understand the tech [#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 [#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

         ```bash
         # 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:

         ```javascript
         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:

         ```javascript
         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:

         ```javascript
         // 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:

      ```javascript
      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 [#implementation]

    This section shows how to implement managing messages.

    The structure of the conversation object is as follows:

    ```javascript
    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 [#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:

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

    ### Retrieve a local conversation [#retrieve-a-local-conversation]

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

    ```javascript
    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 [#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:

    ```javascript
    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 [#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:

    ```javascript
    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 [#delete-a-conversation]

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

    ```javascript
    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 [#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.

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

    ### Synchronize server conversation list to local [#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:

    ```javascript
    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 [#import-the-web-sdk-files-as-required]

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

    | Function            | File for import                                                             | Usage                                                   |
    | :------------------ | :-------------------------------------------------------------------------- | :------------------------------------------------------ |
    | Contact and message | `import \* as contactPlugin from "agora-chat/contact/contact";`             | `miniCore.usePlugin(contactPlugin, "contact");`         |
    | Group               | `import \* as groupPlugin from "agora-chat/group/group";`                   | `miniCore.usePlugin(groupPlugin, "group");`             |
    | Chat room           | `import \* as chatroomPlugin from "agora-chat/chatroom/chatroom";`          | `miniCore.usePlugin(chatroomPlugin, "chatroom");`       |
    | Thread              | `import \* as threadPlugin from "agora-chat/thread/thread";`                | `miniCore.usePlugin(threadPlugin, "thread");`           |
    | Translation         | `import \* as translationPlugin from "agora-chat/translation/translation";` | `miniCore.usePlugin(translationPlugin, "translation");` |
    | Presence            | `import \* as presencePlugin from "agora-chat/presence/presence";`          | `miniCore.usePlugin(presencePlugin, "presence");`       |

    The sample code is as follows:

    ```javascript

    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 [#next-steps]

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

    * [Retrieve conversations and messages from the server](./retrieve-messages)
    * [Message receipts](./message-receipts)