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 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

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.
uml diagram

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.
Was this page helpful?
Yes
No
  • Features
  • Prerequisites
  • Workflow
  • API call sequence diagram
  • Notes
  • Notes
  • API reference