Message Retraction

Estimated reading time: 5 minutes

Message retraction APIs allow users to modify or delete the sent messages. For example, to correct typos or to remove messages they didn’t mean to send.

You can enable or disable different retraction features by specifying retraction policies. You can also configure the max time limit for message retraction. Any messages that are older than the retraction time limit will not be retracted. The default retraction time limit is 1800 seconds which can be set from 1 second to any arbitrarily large value. We will cover retraction policies later in this document.

Type of Retractions

There are primarily three ways to retract messages:

  • Modifying Messages
  • Wiping Messages
  • Deleting Messages

Modifying Messages

The sender can modify an already sent message by sending a new message with the same message ID and by setting a flag to indicate the modification. If the message with the ID exists on the remote end from the same sender, it will be updated. If not, no action will be taken.

You can enable message modification by calling enableModify API of MessageParams.

Note that,

  • Setting a modification flag is mandatory for modifying the message. If not, the message will be considered duplicate and will be discarded.
  • You must not set the flag when sending normal messages.
void MessageParams.enableModify(boolean enable);

enableModify takes the following parameters:

Parameter Description
enable enable (true) or disable (false) message modification.

For example, in Java

Mesibo.MessageParams p = new Mesibo.MessageParams();
p.setPeer(destination);
p.enableModify(true);
Mesibo.sendMessage(p, msgid, "new message");

in iOS

MesiboParams *params = [MesiboParams new];
[params setPeer:destination];
[params enableModify:YES];
[MesiboInstance sendMessage:params msgid:msgid string:@"new message"];

Deleting Messages

The sender can delete sent messages by calling the deleteMessage API with the message ID to be deleted on the local and remote ends.

On the remote end, Mesibo_onMessageStatus will be invoked when a message is deleted by sender which can be used for updating UI, if requires.

boolean deleteMessage(long msgid);
boolean deleteMessage(long msgid, boolean remote);
boolean deleteMessages(long[] msgids, int count);
boolean deleteMessages(long[] msgids, int count, boolean remote);

deleteMessage and deleteMessages take the following parameters:

Parameter Description
msgid message ID to be deleted
msgids message IDs to be deleted
remote true for deleting locally and also on remote end. false to delete only locally.

For example, in Java

Mesibo.deleteMessage(1234, true);

In iOS

[MesiboInstance deleteMessage:1234 remote:YES];

Wiping Messages

Instead of deleting, the sender can wipe an already sent message by calling wipeMessage (locally only) or wipeAndRecalllMessage (both local and remote) APIs. However, if that message was not read, it will be deleted instead.

On the remote end, Mesibo_onMessageStatus will be invoked when a message is deleted by sender which can be used for updating UI, if requires.

boolean wipeMessage(long msgid);
boolean wipeMessages(long[] msgids, int count);
boolean wipeAndRecalllMessage(long msgid);
boolean wipeAndRecalllMessages(long[] msgids, int count);

Above functions take the following parameters:

Parameter Description
msgid message ID to be wiped or deleted
msgids message IDs to be wiped or deleted

For example, in Java

Mesibo.wipeAndRecalllMessage(1234);

In iOS

[MesiboInstance wipeAndRecalllMessage:1234];

Retraction Policies

The app can set the retraction policies to enable or disable certain or all retraction features. The app can also set the max interval after which the retraction of messages will not be allowed.

Retraction Interval

The app can get and set the max retraction interval by using following APIs.

int setMessageRetractionInterval(int seconds);
int getMessageRetractionInterval();

setMessageRetractionInterval takes the following parameters:

Parameter Description
seconds seconds after which retraction will not be allowed.

The default max retraction period is 1800 seconds (30 minutes).

Mesibo.setMessageRetractionInterval(1800);

Retraction Policy

The app can enable or disable different retraction features by using setMessageRetractionPolicy. For example, an app can disable modifying the message but can allow deleting messages remotely.

int setMessageRetractionPolicy(long policy);

setMessageRetractionPolicy takes the following parameters:

Parameter Description
policy can be a logical OR combination of one or more policy flags value below

By default, all the features are enabled.

Flag Description
0 Disable Message Retraction
MESIBO_RETRACT_MODIFY Allow modifying messages
MESIBO_RETRACT_WIPE Allow wiping messages
MESIBO_RETRACT_DELETE Allow deleting messages
MESIBO_RETRACT_DELUNREAD [Future] allow deleting all unread messages
MESIBO_RETRACT_DELREAD [Future] allow deleting all unread messages
MESIBO_RETRACT_DELMEDIA [Future] allow deleting all messages with media
MESIBO_RETRACT_DELTHREAD [Future] allow deleting all messages in conversation threads
MESIBO_RETRACT_DELALL Delete all messages
Mesibo.setMessageRetractionPolicy(MESIBO_RETRACT_MODIFY|MESIBO_RETRACT_WIPE|MESIBO_RETRACT_DELETE);

Retraction Limitation

It is worth understanding some limitations on retraction features.

  • the retraction will not work after the configured retraction period. So if the receiver is offline for a longer duration exceeding the max retraction interval, the retraction request will be rejected.
  • If the message was forwarded, the forwarded message will not be deleted when the original message was retracted.
  • Retraction will only work on supported API versions (1.8.97 and later, latest Javascript).
message retraction, recalling, retraction, disapppearing messages