Recall Message

After successfully sending a message through the IMLib SDK, you may discover errors in the message content and wish to recall it while removing it from the recipient's message history. You can achieve this using the message recall feature.

The recallMessage interface will by default replace the original message in the chat history with a recall notification message (objectName: RC:RcNtf) (RCRecallNotificationMessage). Simultaneously, message recipients can receive server notifications through the messageDidRecall callback method of RCIMClientReceiveMessageDelegate, allowing them to perform corresponding actions and refresh the UI upon receiving the recall notification.

For details about the structure of recall notification messages, refer to the server documentation Notification Message Format.

By default, RC imposes no restrictions on who can recall messages. If restrictions are needed, consider the following approaches:

• The App client can implement its own restrictions. For example, regular users may be prohibited from recalling messages sent by others, while administrator roles may be permitted to do so.
• To prevent users from recalling messages not sent by themselves, you can submit a ticket to enable the IMLib SDK Only Allows Recalling Self-Sent Messages feature. This restriction is enforced at the RC server level, preventing users from recalling messages not sent by them.

The IMLib SDK does not impose time limits on message recalls. However, most mainstream social apps implement recall time limits. We recommend setting your own recall time limits based on the message's sentTime.

Listening for Message Recall Events

When the sender recalls a message, recipients can receive server notifications through the messageDidRecall callback method of RCIMClientReceiveMessageDelegate. Upon receiving the recall notification, they can perform corresponding actions, refresh the UI, or handle other business logic.

Setting the Delegate

To implement this functionality, you must conform to the RCIMClientReceiveMessageDelegate protocol and set the delegate after initializing the IMLib SDK but before connecting to IM:

[[RCCoreClient sharedCoreClient] setReceiveMessageDelegate:self object:nil];

Implementing the Delegate Method

Recipients can listen for recalled messages through the following method:

@protocol RCIMClientReceiveMessageDelegate <NSObject>
/*!
 Callback for message recall

 @param message The recalled message

 @discussion If the original message is not deleted, it will be replaced with an `RCRecallNotificationMessage`. If the original message is deleted, the callback will return the original recalled message. In both cases, it is recommended to refresh this message in the UI.
 */
- (void)messageDidRecall:(RCMessage *)message;
@end

Recalling Messages

tip

• When recalling a specific message, only successfully sent messages can be recalled.
• Starting from version 5.16.1, recall-related parameters can be configured.

Beginning with version 5.16.1, the IMLib SDK supports custom recall configurations via the RCRecallMessageOption object. If the recall succeeds and the isDelete parameter in the recall configuration is set to NO, the success callback will return the modified RCRecallNotificationMessage. If isDelete is set to YES, the success callback will return the deleted original message.

Interface Prototype

- (void)recallMessage:(RCMessage *)message
               option:(nullable RCRecallMessageOption *)option
          pushContent:(nullable NSString *)pushContent
              success:(nullable void (^)(RCMessage *message))successBlock
                error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
message	RCMessage	The message to be recalled
option	RCRecallMessageOption	Configuration options for the recall. Pass nil if no configuration is needed.
pushContent	NSString	The push notification content
successBlock	Block	The message parameter in the callback is the recalled message body. If isDelete is NO, this message has been replaced with a new RCRecallNotificationMessage. If isDelete is YES, this message has been deleted.
errorBlock	Block	Callback for recall failure. errorCode is of type RCErrorCode.

Example Code

/// - Since: 5.16.0
RCRecallMessageOption *option = [[RCRecallMessageOption alloc] init];
option.isDelete = YES;
option.isAdmin = YES;
option.disableNotification = YES;
[[RCCoreClient sharedCoreClient] recallMessage:message option:option pushContent:nil success:^(RCMessage * _Nonnull message) {
    // Returns the complete message body upon success
} error:^(RCErrorCode errorCode) {

}]

For IMLib SDK versions below 5.16.1, the recall interface does not support parameter configuration. Upon successful recall, the interface returns the messageId of the recalled message, which has already been replaced with a gray-bar recall notification message (RCRecallNotificationMessage). You can retrieve this notification message from the database using the getMessage interface and display it in the UI.

/// - Since: 5.0.0
[[RCCoreClient sharedCoreClient] recallMessage:message pushContent:nil success:^(long messageId) {
    // Returns the message ID upon success
} error:^(RCErrorCode errorCode) {

}]

To recall a message using its messageId (a unique local database index) or messageUId (a unique server message ID), first retrieve the message using one of the following methods, then use recallMessage to recall it.

• getMessage
• getMessageByUId