Unsend a message
Update time: 2024/03/07 11:13:59
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 inNIMSDKOptions
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
-
User A and User B call
onMessageRevoked
to register the observer for unsending messages. The observer can track notificationsNIMRevokeMessage
for events of unsending messages.-
NIMRevokeMessage
representationParameterTypeDescription 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 themsg
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
dart
NimCore.instance.messageService.onMessageRevoked.listen((event) { print('Test_Observer onMessageRevoked ${event.toString()}'); });
-
-
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 anduuid
as value using theNIMMessage.pushPayload
method. It is the unique identifier of the message. - When the message is recalled, specify the message body in the
customApnsText
parameter in therevokeMessage
method to override the text of the recalled message and add the same key-value pair ofapns-collapse-id
inpushPayload
.
API reference
API |
Description |
---|---|
onMessageRevoked |
Register the event stream of unsending a message and listen to the unsend event. |
revokeMessage |
Unsend a message. |