Unsend Messages - Instant Messaging

Update time: 2022/12/09 03:29:55

You can recall a sent message for yourself or for all participants. Recalling messages in one-to-one private chats and group chats differs:

One-to-one private chat: Only the sender can recall a message.
Group chat: Group members can recall messages sent by themselves. NIM SDK allows administrators to recall messages sent by other members (the server API does not support this feature).

Recall messages

Recall one-to-one and group chat messages for every one 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 messages, and message history.

You can log in to the CommsEase console, select Projects, and then go to IM Pro/IM Free > Configuration > Message Recall Duration to set the duration. Up to 604800 seconds (7 days) is allowed.

Rate limit

Apps can call the API by 100 times per second. If an app calls the API exceeding the limit, requests from the app will be blocked for 10 seconds before the API become available again.
You cannot recall messages if: the message is empty; the message is not sent successfully; the recipient is yourself.
If the message is hit by the content moderation service, an error (status code: 414) will be thrown when you recall the message.
If an account has left the group or is removed from the group when recalling a group message, the error {"desc": "not allow!", "code": 403} occurs. However, within the revocable duration, you can still recall the message in the valid period using the following methods:
- Call the server APIRecall message for yourself(NIM SDK v7.2.0 or later).
- Administrators can recall messages sent by group members by calling the specified method in NIM SDK.

URL

httpPOST https://api.netease.im/nimserver/msg/recall.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

For information about how to set the header in a POST request, see API Call methods.
The settings of the body in a POST request:

Parameter	Type	Required	Description
deleteMsgid	Long	Yes	ID of the message to recall
timetag	Long	No	The time when the message was created (timestamp on the CommsEase server when the message was sent). For example, "12514613452"
type	int	Yes	Only 7 or 8 is valid. 7: one-to-one message 8: group message Other values throw an error.
from	String	Yes	IM account (accid) of the sender
to	String	Yes	IM account (accid) for one-to-one messages. Group ID (tid) for group messages
msg	String	No	The description for recalling a message. The default value is "The message was recalled". The description can contain up to 128 characters.
ignoreTime	String	No	Only 1 is valid. The value 1 indicates that the time check for recalling is ignored. Other values are invalid. If you set the value to 1, messages sent for up to the last 30 days can be recalled. If you do not need the time check for recalling messages, you can leave the field empty.
pushcontent	String	No	Body of a push notification. This field displays the body of a push notification on Android devices, and the content of pushcontent on iOS apps if the payload is unspecified. Text longer than 500 characters will be removed.
payload	String	No	The payload of a push notification in JSON. The value cannot exceed 2,000 characters.
env	String	No	The environment name for data sync, consistent with the environment name specified in the CommsEase console for data sync as shown in the figure below. A maximum of 32 characters are allowed. ![Custom environment.png](https://yx-web-nosdn.netease.im/common/67dfaa431a321abfb77e5f238da47b62/Custom environment.png)
attach	String	No	Extension field that can contain up to 5,000 characters.

Example

cURL request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kg*****3mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'deleteMsgid=10386192&timetag=1481528155741&type=7&from=t1&to=t4&msg=这是一条撤回消息'  'https://api.netease.im/nimserver/msg/recall.action'

Example success response

HTTP response in JSON

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

Example error response

json"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"msgidclient is null"  // deleteMsgid is empty
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes.

If parameters, such as deleteMsgid, from, and to are invalid (the corresponding message does not exist), the server will directly return a 200 response. In this case, the message is deemed recalled successfully.

Status code	Description	Recommendation
403	Possible reasons for a failed request: Authentication failed The message cannot be recalled.	Handle the error based on the specific error message.
414	Parameter error	Check the format and restrictions of arguments based on the error message.
416	Rate limit. Too many requests within a short period of time	Lower the number of requests.
500	Internal Server Error	-

Recall a message for the current user

Overview

Recall one-to-one or group messages for the current user. 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 message history. The sender receives no indications and the roaming message and message history remain unchanged.

This API can recall messages within a maximum of 30 days and is not limited by the time limit setting specified in the CommsEase console.