The MessageService class provides methods used to unsend messages and corresponding listeners. The SDK allows you to unsend multiple types of messages, such as unsending a message for yourself and unsending messages for all members in group chats using revokeType.

Features

Type	Description
Unsend a sent message for all participants	Users can undo a sent message for all participants in P2P chats and group chats within a certain period of time (two minutes by default). You can change the default value in the CommsEase console. After a message is recalled, the sender and recipients receive a notification and the message is deleted from the corresponding offline messages, roaming message, and message history.
Unsend a sent message for the current user	Unsend P2P and group messages for the current user within a certain period of time (two minutes by default). You can change the default value in the CommsEase console. After a message is recalled, recipients receive a notification for the recalled message and the message is deleted from the corresponding offline messages, roaming message and and message history. The sender receives no indications and the roaming message and message history remain unchanged.

• When initializing SDK, set the shouldConsiderRevokedMessageUnreadCount parameter in NIMSDKOptions to true to recalculate the unread count after the message is unsent.
• Recalling messages in P2P chats and group chats differs:
  • In P2P chats, you can unsend messages sent by yourself.
  • Group chat: Group members can recall messages sent by themselves. NIM SDK allows administrators to recall messages sent by other group members (the server API does not support this feature).

Prerequisites

• The SDK is initialized.
• IM accounts are created.

Workflow

The process for recalling messages of different types is similar. This section describes how to unsend messages in a private chat between User A and User B.

API call sequence diagram

The sequence diagram below only takes the scenario where a message is unsent for all participants in a P2P chat.

• The sequence diagrams in this article may display abnormally due to network problems. To fix the displayed problem, refresh the current page.

Notes

1. User A and User B call onMessageRevoked to register the observer for unsending messages. The observer can track notifications NIMRevokeMessage for events of unsending messages.

   • NIMRevokeMessage representation

     Parameter	Type	Description
     attach	String	message attachment
     customInfo	String	When unsending a message using the server API ([nimservermsg/recall.action](https://doc.commsease.com/messaging/docs/zE1NjUyNDg?platform=server#request parameter)), set the value to the msg field. The field indicates the description for unsending a message. The default value is "The message was unsent".
     message	NIMMessage	The unsent message.
     notificationType	int	Type of message to be unsent. 0: online message, 1: offline message, 2: roaming message. The default value is 0.
     revokeType	RevokeMessageType	The types of unsend operations, unsending or deleting a message for all participants of P2P chats, group chats, supergroup chats, and unsending or deleting a message for the current user only, and undefined type. The types are not supported on Windows and macOS.
     	fromAccount	String	the account that unsends a message.
     callbackExt	String	custom extension field.

   • Example

     dartNimCore.instance.messageService.onMessageRevoked.listen((event) {
     print('Test_Observer onMessageRevoked ${event.toString()}');
     });
     
     
     

2. User A sends a message and unsends the sent message by calling revokeMessage. After the call is successful, the SDK will trigger a callback to notify the upper layer of your app that the message is recalled and automatically delete the local message. If you want to display an alert that you have recalled a message, you can construct an alert message and call the method of inserting local messages.

Recalling a message fails if:

• a message is empty.
• a message fails to be sent
• The validity duration expires for recalling a message
• a message is filtered by the content moderation service.

Parameter	Type	Description
message	NIMMessage	The unsent message.
customApnsText	String	Optional Custom push text. If the parameter is not specified, no push notifications will be sent.
pushPayload	Map<String, Object>	Custom push payload in JSON format with a maximum of 2048 characters.
shouldNotifyBeCount	bool	whether the unread count is updated when a message is unsent. The parameter is not supported on Windows and macOS.
postscript	String	Optional. The additional message. The parameter is not supported on Windows and macOS.
attach	String	Optional. The extension field.

** Sample code**:

dartNimCore.instance.messageService.revokeMessage(message: message);

Notes

For the requirement of overwriting the body of an unsent message, use the following implementation. For example, User A sends a message to User B and triggers APNs push. The message body is "Hello". User A unsends the message, and the message body "Hello" displayed on the notification bar is replaced by the preset message "A message was recalled".

• Add a key-value pair of apns-collapse-id as key and uuid as value using the NIMMessage.pushPayload method. It is the unique identifier of the message.
• When the message is recalled, specify the message body in the customApnsText parameter in the revokeMessage method to override the text of the recalled message and add the same key-value pair of apns-collapse-id in pushPayload.

API reference

API	Description
onMessageRevoked	Register the event stream of unsending a message and listen to the unsend event.
revokeMessage	Unsend a message.