Skip to main content
Android
iOS
Web
Windows
Unity
Flutter
React Native

Manage server-side messages

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.

This page introduces how to use the Chat SDK to retrieve and delete messages from the server.

Understand the tech

The Chat SDK uses ChatManager to retrieve historical messages from the server. The followings 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.
  • removeMessagesFromServer: Deletes historical messages from the server unidirectionally.
  • deleteConversationFromServer: Deletes conversations and their historical messages from the server.

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 asyncFetchConversationsFromServer 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. Otherwise, you can call getAllConversations to retrieve conversations on the local device. The server stores 100 conversations for 7 days by default. To increase the two upper limits, contact support@agora.io. Agora Chat server can store up to 3,000 conversation per end user.


_29
String cursor = "";
_29
limit: The number of conversations that you expect to get on each page. The value range is [1,50].
_29
int limit = 40;
_29
List<Conversation> conversations = new ArrayList<>();
_29
doAsyncFetchConversationsFromServer(limit,cursor,conversations);
_29
_29
private void doAsyncFetchConversationsFromServer(final int limit, final String cursor,List<Conversation> conversations){
_29
ChatClient.getInstance().chatManager().asyncFetchConversationsFromServer(limit, cursor, new ValueCallBack<CursorResult<Conversation>>() {
_29
@Override
_29
public void onSuccess(CursorResult<Conversation> value) {
_29
if (value != null ) {
_29
List<Conversation> list = value.getData();
_29
if (list != null && list.size() > 0) {
_29
conversations.addAll(list);
_29
}
_29
String newCursor = value.getCursor();
_29
if( !TextUtils.isEmpty(newCursor)) {
_29
doAsyncFetchConversationsFromServer(limit, newCursor, conversations);
_29
}
_29
}
_29
_29
}
_29
_29
@Override
_29
public void onError(int error, String errorMsg) {
_29
_29
}
_29
});
_29
}

Retrieve historical messages 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:1 private chat: Store 500 offline messages by default;
  • Chat Group: Store 200 offline messages by default;
  • Chatroom: Doesn't store offline messages. However, whenever an end user joins a chatroom, Agora Chat servers push the 10 latest messages/chatroom to them, by default. This number can be adjusted to 200 messages/chatroom without additional charges.

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.

Refer to the following code sample:


_36
String conversationId=" ";
_36
Conversation.ConversationType type=Conversation.ConversationType.Chat;
_36
FetchMessageOption option=new FetchMessageOption();
_36
//for example
_36
//option.setIsSave(true);
_36
int pageSize = 40;
_36
String cursor = "";
_36
List<ChatMessage> messages = new ArrayList<>();
_36
doAsyncFetchHistoryMessages(conversationId,type,pageSize,cursor,option,messages);
_36
_36
private void doAsyncFetchHistoryMessages(String conversationId,
_36
Conversation.ConversationType type,
_36
int pageSize,String cursor,
_36
FetchMessageOption option,
_36
List<ChatMessage> messages){
_36
ChatClient.getInstance().chatManager().asyncFetchHistoryMessages(conversationId, type, pageSize, cursor, option, new ValueCallBack<CursorResult<ChatMessage>>() {
_36
@Override
_36
public void onSuccess(CursorResult<ChatMessage> value) {
_36
if (value != null ) {
_36
List<ChatMessage> list = value.getData();
_36
if (list != null && list.size() > 0) {
_36
messages.addAll(list);
_36
}
_36
String newCursor = value.getCursor();
_36
if( !TextUtils.isEmpty(newCursor)) {
_36
doAsyncFetchHistoryMessages(conversationId, type, pageSize, newCursor, option, messages);
_36
}
_36
}
_36
}
_36
_36
@Override
_36
public void onError(int error, String errorMsg) {
_36
_36
}
_36
});
_36
}

Pin a conversation

To keep track of an important conversation, you can pin it to the top of your conversation list. You can pin up to 50 conversations. The pinned state is stored on the server. In a multi-device login scenario, if you pin or unpin a conversation, other login devices will receive the CONVERSATION_PINNED or CONVERSATION_UNPINNED events.

Refer to the following code example to pin a conversation:


_9
ChatClient.getInstance().chatManager().asyncPinConversation(conversationId, true, new CallBack() {
_9
@Override
_9
public void onSuccess() {
_9
}
_9
_9
@Override
_9
public void onError(int code, String error) {
_9
}
_9
});

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:


_28
// limit: The number of sessions returned per page. The value range is [1,50].
_28
// cursor: The cursor position to start getting data. If `null` or an empty string ("") is passed when obtaining data, the SDK will start querying from the latest pinned session.
_28
String cursor = "";
_28
int limit = 40;
_28
List<Conversation> conversations = new ArrayList<>();
_28
doAsyncFetchPinnedConversationsFromServer(limit,cursor,conversations);
_28
_28
private void doAsyncFetchPinnedConversationsFromServer(final int limit, final String cursor,List<Conversation> conversations){
_28
ChatClient.getInstance().chatManager().asyncFetchPinnedConversationsFromServer(limit, cursor, new ValueCallBack<CursorResult<Conversation>>() {
_28
@Override
_28
public void onSuccess(CursorResult<Conversation> value) {
_28
if (value != null) {
_28
List<Conversation> list = value.getData();
_28
if (list != null && list.size() > 0) {
_28
conversations.addAll(list);
_28
}
_28
String newCursor = value.getCursor();
_28
if( !TextUtils.isEmpty(newCursor)) {
_28
doAsyncFetchPinnedConversationsFromServer(limit, newCursor, conversations);
_28
}
_28
}
_28
}
_28
_28
@Override
_28
public void onError(int error, String errorMsg) {
_28
}
_28
});
_28
}

Delete historical messages from the server unidirectionally

Call removeMessagesFromServer to delete historical messages one way from the server. You can remove a maximum of 50 messages from the server each time. Once the messages are deleted, you can no longer retrieve them from the server. The deleted messages are automatically removed from your local device. Other chat users can still get the messages from the server.


_20
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(username);
_20
// Delete messages by timestamp
_20
conversation.removeMessagesFromServer(beforeTimeStamp, new CallBack() {
_20
@Override
_20
public void onSuccess() {
_20
}
_20
@Override
_20
public void onError(int code, String error) {
_20
}
_20
});
_20
// Delete messages by message ID
_20
conversation.removeMessagesFromServer(msgIdList, new CallBack() {
_20
@Override
_20
public void onSuccess() {
_20
_20
}
_20
@Override
_20
public void onError(int code, String error) {
_20
}
_20
});

Call deleteConversationFromServer to delete conversations and their historical messages unidirectionally from the server. After the conversations and messages are deleted from the server, you can no longer get them from the server. The deleted conversations still exist on your local device, but the messages are automatically removed from the device. Other chat users can still get the conversations and their historical messages from the server.


_10
ChatClient.getInstance().chatManager().deleteConversationFromServer(conversationId, conversationType, isDeleteServerMessage, new CallBack() {
_10
@Override
_10
public void onSuccess() {
_10
_10
}
_10
_10
@Override
_10
public void onError(int code, String error) {
_10
}
_10
});

Next steps

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

vundefined