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

Manage server-side messages

Updated

Introduces how to use the Agora Chat SDK to retrieve messages from the server.

The Chat SDK stores historical messages on the chat server. When a chat user logs in from a different device, you can retrieve the historical messages from the server, so that the user can also browse these messages on the new device. Additionally, the Chat SDK supports adding tags to conversation, with a maximum of 20 tags allowed per conversation.

This page introduces how to use the Chat SDK to retrieve, delete, and tag messages and conversations.

Understand the tech

The Chat SDK uses ChatManager to retrieve historical messages from the server. The following are the core methods:

  • asyncFetchConversationsFromServer: Retrieves a list of conversations stored on the server.
  • asyncFetchHistoryMessages: Retrieves historical messages of a conversation from the server according to FetchMessageOption, the parameter configuration class for retrieving historical messages.
  • asyncPinConversation: Pins conversations.
  • asyncFetchPinnedConversationsFromServer: Retrieves pinned conversations.
  • asyncPinMessage: Pins a message in a conversation.
  • asyncUnPinMessage: Unpin a message in a conversation.
  • asyncGetPinnedMessagesFromServer: Get a list of pinned messages in a conversation.
  • removeMessagesFromServer: One-way deletion of historical messages on the server based on message time or message ID.
  • deleteConversationFromServer: Deletes conversations and their historical messages from the server.
  • asyncAddConversationMark: Tags a conversation.
  • asyncRemoveConversationMark: Removes a conversation tag.
  • asyncGetConversationsFromServerWithCursor: Queries conversations from the server by a conversation tag.

The Chat SDK uses ChatManager to retrieve historical messages from the server. The following are the core methods:

  • getServerConversations: Retrieves a list of conversations stored on the server with pagination.
  • getHistoryMessages: Retrieves the historical messages in the specified conversation from the server.
  • pinConversation: Pin a conversation.
  • getServerPinnedConversations: Retrieves a list of pinned conversations.
  • pinMessage: Pins a message in a conversation.
  • unpinMessage: Unpin a message in a conversation.
  • getServerPinnedMessages: Get a list of pinned messages in a conversation.
  • removeHistoryMessages: Deletes historical messages from the server unidirectionally.
  • deleteConversation: Deletes conversations and their historical messages from the server.
  • addConversationMark: Tags a conversation.
  • removeConversationMark: Removes a conversation tag.
  • getServerConversationsByFilter: Queries conversations from the server by a conversation tag.

Prerequisites

Before proceeding, ensure that you meet the following requirements:

  • You have integrated the Chat SDK, initialized the SDK and implemented the functionality of registering accounts and login. For details, see Chat SDK quickstart.
  • You understand the API call frequency limits as described in Limitations.

Implementation

This section shows how to implement retrieving conversations and messages.

Retrieve a list of conversations from the server

Call getServerConversations to retrieve conversations from the server with pagination. The SDK returns the conversation list in the reverse chronological order of when conversations are active (the timestamp of the last message in the conversation). In the conversation list, each conversation object contains the conversation ID, conversation type, whether the conversation is pinned, the pinned time (the value is 0 for an unpinned conversation), and the last message in the conversation. After the conversation list is retrieved from the server, the local conversation list will be updated accordingly. We recommend calling this method when the app is first installed, or when there is no conversation on the local device.

For each end user, the server stores 100 conversations by default. When this limit is exceeded, new conversations will start overwriting the old ones. If the entire message history in a conversation expires, the conversation becomes empty. When pulling the conversation list from the server, these empty conversations are not included. However, if there are empty conversations on the server, they will occupy the conversation list quota. To change this, contact support@agora.io.

Do not use mixed upper-case.

// pageSize: The number of conversations that you expect to get on each page. The value range is [1,50] and the default value is `20`.
// cursor: The cursor position for starting to get data. If you pass in an empty string (''), the SDK retrieves conversations from the latest active one.
chatClient.getServerConversations({ pageSize: 50, cursor: "" }).then((res) => {
  console.log(res);
});

Retrieve message history of the specified conversation

After retrieving conversations, you can retrieve historical messages from the server.

You can set the search direction to retrieve messages in the chronological or reverse chronological order of when the server receives them, the message type, the time period, the message sender, as well as whether to save the retrieved message to the local database.

If you have integrated Chat SDK after June 8, 2023, you can retrieve historical messages even before joining the Chat Group. For earlier implementations, contact support@agora.io to enable this.

The Agora Chat server stores the full message history for a certain period of time depending on your subscribed Chat plan. After an end user logs back into Agora Chat, the servers automatically send offline messages to them, that is, messages transmitted when that end user was offline. Offline messages are a subset of the full message history stored on Agora Chat server. Sending only a subset of messages prevents distributing too many messages to a single device, which can overwhelm it and slow down the end user login. Agora Chat server stores and manages these offline messages for every end user in the following way:

  • 1
    private chat: Store 500 offline messages by default;
  • Chat Group: Store 200 offline messages by default;
  • Chatroom: Doesn't store offline messages. However, by default, whenever an end user joins a chatroom, Agora Chat servers push the 10 latest messages/chatroom to them, and this number can be adjusted to 200 messages/chatroom without additional charges.

After the GA release of Agora Chat 1.3, you can log in to Agora Console and enable the chatroom message history retrieval feature. After that, Agora Chat servers will stop automatically pushing chatroom messages to new members and you can follow the guidance below to retrieve chatroom message history.

For users to receive more offline messages, use the client API or a webhook to sync with Agora Chat's server. End users can also store additional messages on their local database.

To ensure data reliability, we recommend retrieving less than 50 historical messages for each method call. To retrieve more than 50 historical messages, call this method multiple times. Once the messages are retrieved, the SDK automatically updates these messages in the local database.

We recommend that you retrieve 20 messages each time, with a maximum of 50. During paginated query, if the total number of messages that meet the query conditions is greater than the number of pageSize, the number of messages of pageSize will be returned. If it is less than the number of pageSize, the actual number will be returned. When the message query is completed, the number of returned messages is less than the number of pageSize.

Since SDK v1.4.0, for a single group conversation you can retrieve messages sent by a specific member by setting from in searchOptions.

Refer to the following code sample:

chatClient.getHistoryMessages({
  targetId: "targetId", // The user ID of the peer user for one-to-one chat or group ID for group chat.
  chatType: "groupChat", // The chat type: `singleChat` for one-to-one chat or `groupChat` for group chat.
  pageSize: 20, // The number of messages to retrieve per page. The value range is [1,50] and the default value is 20.
  searchDirection: "down", // The message search direction: `up` means to retrieve messages in the descending order of the message timestamp and `down` means to retrieve messages in the ascending order of the message timestamp.
  searchOptions: {
    from: "message sender userID", // The user ID of the message sender. This parameter is used only for group chat.
    msgTypes: ["txt"], // An array of message types for query. If no value is passed in, all types of message will be queried.
    startTime: new Date("2023,11,9").getTime(), // The start timestamp for query. The unit is millisecond.
    endTime: new Date("2023,11,10").getTime(), // The end timestamp for query. The unit is millisecond.
  },
});

Pin a conversation

Refer to the following code example to pin a conversation:

chatClient.pinConversation({
  conversationId: "conversationId",
  conversationType: "singleChat",
  isPinned: true,
});

Retrieve the pinned conversations from the server with pagination

End users can pin up to 50 conversations. After you call this API, the SDK returns the pinned conversations in the reverse chronological order of when they are pinned.

Agora Chat servers store a list of conversations that remain active in the past 7 days, regardless of Agora Chat package subscription. A conversation is considered active if it is pinned or there are new messages in a conversation.

Refer to the following code example to get a list of pinned conversations from the server with pagination:

// pageSize: The number of sessions returned per page. The value range is [1,50]。
// cursor：The cursor position to start getting data. If an empty string ('') is passed, the SDK will start querying from the latest pinned session.
chatClient.getServerPinnedConversations({ pageSize: 50, cursor: "" });

Pin a message

You can call pinMessage to pin a message to the top of a one-to-one chat, chat group, or chat room. When the pinned status of a message changes, other members in the group or chat room conversation will receive the onMessagePinEvent event. In the case of multi-device login, the updated top status will be synchronized to other logged-in devices, and other devices will receive the onMessagePinEvent event, respectively.

In group and chat room conversations, multiple users can pin the same message to the top. The latest pinned message will overwrite the earlier information. That is, the PinnedMessageInfo user ID and pin time will correspond to the latest pinned message.

For a single conversation, 20 messages can be pinned to the top by default.

const options = {
  // Conversation type which is `groupChat` for group chat and `chatRoom` for chat room chat.
  conversationType: "groupChat",
  // Conversation ID.
  conversationId: "conversationId",
  // Message ID.
  messageId: "messageId",
};

chatClient.pinMessage(options).then(() => {
  // Succeeded in pinning the message.
  console.log("Succeeded in pinning the message");
});

Unpin a message

You can call unpinMessage to unpin a message in a one-to-one chat, chat group, or chat room. As with pinned messages, other members of the group or chat room will receive the onMessagePinEvent event when the pinned message is unpinned. In the case of multi-device login, the updated pin status will be synchronized to other logged-in devices, and other devices will receive the onMessagePinEvent event, respectively.

Any user in a group or room can unpin a message, regardless of who pinned it. After unpinning a message, the message is no longer included in the pinned message list.

const options = {
  // Conversation type which is `groupChat` for group chat and `chatRoom` for chat room chat.
  conversationType: "groupChat",
  // Conversation ID.
  conversationId: "conversationId",
  // Message ID.
  messageId: "messageId",
};

chatClient.unpinMessage(options).then(() => {
  // Succeeded in unpinning the message.
  console.log("Succeeded in unpinning the message.");
});

Get pinned messages in a single conversation

You can call getServerPinnedMessages to get the pinned messages from a single conversation from the server. The SDK returns messages in the reverse order of pinning.

If a message expires on the server or the user deletes it unilaterally from the server after pinning, such user will not be able to pull it when pulling roaming messages. However, this user and other users will be able to pull this message from the pinned message list.

If the user withdraws a message after pinning, the message will be removed from the server; other users will not be able to pull it when they pull the pinned message list from the server.

const options = {
  // Conversation ID.
  conversationId: "conversationId",
  // Conversation type which is `groupChat` for group chat and `chatRoom` for chat room chat.
  conversationType: "groupChat",
  // The number of pinned messages to retrieve per page. The value range is [1,50] and the default value is `10`
  pageSize: 20,
  // The cursor position that indicates where to start getting data.
  // Pass in an empty string ('') for the first call of the API and the SDK returns the pinned messages in the descending order of the pinning time.
  cursor: "",
};

chatClient.getServerPinnedMessages(options).then((res) => {
  // Succeeded in retrieving the list of pinned messages in a conversation.
  console.log(res);
});

Delete historical messages from the server unidirectionally

Call removeHistoryMessages to delete historical messages one way from the server. You can remove a maximum of 20 messages from the server each time. Once the messages are deleted, you can no longer retrieve them from the server. Other chat users can still get the messages from the server.

// Delete messages by timestamp
chatClient.removeHistoryMessages({
  targetId: "userId",
  chatType: "singleChat",
  beforeTimeStamp: Date.now(),
});
// Delete messages by message ID
chatClient.removeHistoryMessages({
  targetId: "userId",
  chatType: "singleChat",
  messageIds: ["messageId"],
});

You can use the removeHistoryMessages method to unidirectionally delete historical messages on the server based on time or message ID. Up to 20 messages can be deleted at once. After deletion, the account cannot retrieve the message from the server. Other users are not affected by this operation.

Upon successful deletion, the deleteRoaming callback will be triggered when logging in from multiple terminals and devices.

// Delete messages by time stamp
chatClient.removeHistoryMessages({
  targetId: "userId",
  chatType: "singleChat",
  beforeTimeStamp: Date.now(),
});

// Delete messages by message ID
chatClient.removeHistoryMessages({
  targetId: "userId",
  chatType: "singleChat",
  messageIds: ["messageId"],
});

Tag a conversation

To tag a conversation, use the addConversationMark method. This method allows you to add tags to both local and server-side conversations. Each conversation can have up to 20 tags. This feature applies only to private chats and chat groups.

After adding a tag, you can retrieve the tagged conversations from the server by calling the getServerConversations method. The returned conversation objects will include the conversation tag, which you can obtain using the ConversationItem#marks method.

If the server conversation list reaches its limit (default 100 conversations per user), inactive conversations will be deleted based on conversation activity (timestamp of the latest message). Consequently, the conversation tags of these deleted conversations will also be removed.

Adding tags to a conversation, such as stars, does not affect other logic of the conversation, such as the number of unread messages in it.

const options = {
  conversations: [
    { conversationId: "test", conversationType: "singleChat" },
    { conversationId: "groupId", conversationType: "groupChat" },
  ],
  mark: 0,
};

chatClient.addConversationMark(options).then(() => {
  console.log("addConversationMark success");
});

To create customized tags, you need to do the following:

const MarkMap = new Map();
MarkMap.set(0, "IMPORTANT");
MarkMap.set(1, "NORMAL");
MarkMap.set(2, "STAR");

Remove conversation tag

To remove a conversation tag, call removeConversationMark. Calling this method removes both the local and server-side conversation tags.

const options = {
  conversations: [
    { conversationId: "test", conversationType: "singleChat" },
    { conversationId: "groupId", conversationType: "groupChat" },
  ],
  mark: 0,
};

chatClient.removeConversationMark(options).then(() => {
  console.log("removeConversationMark success");
});

Query conversations from the server by the conversation tag

You can use the getServerConversationsByFilter method to retrieve a list of conversations from the server based on the tag. The SDK returns the conversation list in the reverse order of the conversation tag's timestamp. Each conversation object includes the following information:

  • Conversation ID
  • Conversation type
  • Pinned status (whether it is pinned or not)
  • Pin time (For an unpinned conversation, the value is 0)
  • Conversation tag
  • Latest message

After fetching the conversation list from the server, the local conversation list is updated accordingly:

const options = {
  pageSize: 10,
  cursor: "",
  filter: {
    mark: 0,
  },
};
chatClient.getServerConversationsByFilter().then((res) => {
  console.log("getServerConversationsByFilter success", res);
});

Next steps

After implementing retrieving 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