Delete Messages

Participants in one-to-one chats and group chats can delete messages within conversations. The IMKit chat UI has built-in long-press-to-delete functionality, supporting both local-only deletion and synchronized deletion of local and remote messages.

You can modify the behavior of the delete button in the IMKit message long-press menu. For details, see Chat UI. If IMKit's default implementation doesn't meet your needs, you can directly use the message deletion APIs provided by the IMKit SDK, which automatically refresh both the conversation list and chat UI.

tip

• By default, messages in one-to-one chats, group chats, and system conversations are only stored in the local database and can only be deleted locally. If your app (App Key/environment) has enabled Cloud Storage for One-to-One and Group Messages, user messages will also be stored on RC servers (default retention: 6 months) and can be deleted from remote history.
• For one-to-one and group chats: When deleting remote messages via timestamp-based APIs, the server won't delete corresponding offline message compensation by default (this mechanism only activates when Multi-Device Message Synchronization is enabled). If users log in from another device or reinstall the app, they may still receive deleted messages via the message compensation mechanism. To completely remove message compensation, submit a ticket to enable deleting offline message compensation when removing server-side history. When deleting via message object-based APIs, the server will simultaneously remove corresponding messages from compensation.

Delete Both Local and Remote Messages

Use these interfaces to delete messages from both local storage and servers:

• The deleteMessages method with cleanRemote parameter set to true. See Delete by Timestamp under "Delete Local Messages."
• The deleteRemoteMessages method. See Delete by Message under "Delete Remote Messages."

Delete Local Messages

Delivered messages are stored directly in the local database. You can call APIs to delete them locally, which automatically refreshes both the conversation list and chat UI.

tip

If Cloud Storage for One-to-One and Group Messages is enabled, local deletion doesn't affect server-stored history. Clients can still retrieve deleted messages from the server.

To delete messages locally only, use these IMKit SDK capabilities:

• Delete one or multiple messages from a specific conversation's local history by message ID.
• Delete all local messages from a specific conversation by conversation ID.
• Delete messages older than a specified timestamp from a conversation's local history. Note: The timestamp-based API includes a cleanRemote parameter to optionally delete corresponding server history.

Delete by Message ID

Use IMCenter's deleteMessages method to delete one or multiple messages by ID from a conversation's local storage. The interface refreshes both chat UI and conversation list upon success. Ensure all provided message IDs belong to the same conversation.

Interface

IMCenter.getInstance().deleteMessages(conversationType, targetId, messageIds，callback);

Parameters

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID
messageIds	int[]	Array of message IDs
callback	IRongCallback.ResultCallback<Boolean>	Callback interface

Delete by Conversation

Use IMCenter's deleteMessages method to delete all local messages from a specific conversation. Success triggers refresh of both chat UI and conversation list.

Interface

IMCenter.getInstance().deleteMessages(conversationType, targetId, callback);

Parameters

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID
callback	IRongCallback.ResultCallback<Boolean>	Callback interface

Sample Code

ConversationType conversationType = ConversationType.PRIVATE; //Example uses private chat
String targetId = "Conversation ID";

IMCenter.getInstance().deleteMessages(conversationType, targetId, new RongIMClient.ResultCallback<Boolean>() {
        @Override
        public void onSuccess(Boolean bool) {
            // Success callback
        }
        @Override
        public void onError(RongIMClient.ErrorCode errorCode) {
            // Failure callback
        }
    });

Delete by Timestamp

Use IMCenter's cleanHistoryMessages method to delete local messages older than a specified timestamp from a conversation.

tip

This method includes a cleanRemote parameter to optionally delete corresponding server messages. You can also use other methods described in Delete Both Local and Remote Messages.

Interface

IMCenter.getInstance().cleanHistoryMessages(conversationType, targetId, recordTime, false, callback);

Parameters

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	String	Conversation ID
recordTime	long	Timestamp. 0 deletes all messages; non-zero deletes messages ≤ recordTime
cleanRemote	boolean	Whether to delete server messages. true for yes, false for no.
callback	OperationCallback	Callback interface

Sample Code

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Conversation ID";
// Example deletes messages older than current timestamp
long recordTime = System.currentTimeMillis();

IMCenter.getInstance().cleanHistoryMessages(conversationType, targetId, recordTime, false, new RongIMClient.OperationCallback() {
    @Override
    public void onSuccess() {
        // Success callback
    }
    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {
        // Failure callback
    }
});

Delete Remote Messages

IMKit SDK's remote message deletion APIs delete messages from both server and local storage. To delete server messages only:

• Use server APIs. See Message Deletion in the server API docs.
• Use IMLib methods to delete messages older than a timestamp from a conversation (see Delete by Timestamp). Note: IMLib doesn't refresh UIs automatically—implement custom notifications as needed.

To delete both local and remote messages via IMKit:

• Use deleteMessages with timestamp and conversation ID, setting cleanRemote to true. See Delete by Message ID.
• Use deleteRemoteMessages with message objects to delete one or multiple messages from both server and local storage. See below.

Delete by Message

Use IMCenter's deleteRemoteMessages to delete one or multiple messages from both server and local storage by conversation type, ID, and message array. Success triggers UI refresh. Ensure all message IDs belong to the same conversation.

For security and performance, deletion APIs enforce two restrictions:

• Operation scope: Single API call limited to one conversation to prevent cross-conversation errors.
• Quantity limit: Android allows max 100 messages per call to prevent performance issues.

Interface

IMCenter.getInstance().deleteRemoteMessages(conversationType, targetId, messages, callback);

Parameters

Parameter	Type	Description
conversationType	ConversationType	Conversation type (chatrooms unsupported)
targetId	String	Conversation ID
messages	Message[]	Array of messages to delete
callback	ResultCallback<Boolean>	Callback interface

Sample Code

ConversationType conversationType = ConversationType.PRIVATE; //Private chat example
String targetId = "Conversation ID";
Message[] messages = {message1, message2};

IMCenter.getInstance().deleteRemoteMessages(conversationType, targetId, messages, new RongIMClient.OperationCallback() {
    @Override
    public void onSuccess() {
        // Success callback
    }
    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {
        // Failure callback
    }
});