Unsend Messages

Update time: 2022/12/09 11: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

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

ParameterTypeRequiredDescription
deleteMsgid Long Yes ID of the message to recall
timetag LongNo The time when the message was created (timestamp on the CommsEase server when the message was sent). For example, "12514613452"
type intYes Only 7 or 8 is valid.
  • 7: one-to-one message
  • 8: group message

Other values throw an error.
fromStringYes IM account (accid) of the sender
toStringYes IM account (accid) for one-to-one messages. Group ID (tid) for group messages
msg StringNo The description for recalling a message. The default value is "The message was recalled". The description can contain up to 128 characters.
ignoreTime StringNo 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.
pushcontentStringNoBody 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.
payloadStringNoThe 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)

attachStringNoExtension field that can contain up to 5,000 characters.

Example

cURL request example

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

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

Example error response

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

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.

URL

POST https://api.netease.im/nimserver/msg/delMsgOneWay.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:

ParameterTypeRequiredDescription
deleteMsgid Long Yes ID of the message to recall
timetag longNo The time when the message was created (timestamp on the CommsEase server when the message was sent). For example, "12514613452"
type intYes The type of the message to be recalled. Only 13 or 14 are valid. 13: one-to-one message; 14: group message. Other values are invalid.
fromStringYes IM account (accid) of the sender
toStringYes Recipient. IM account (accid) for one-to-one messages. Group ID (tid) for group messages
msg StringNo The description for recalling a message. The default value is "The message was recalled". The description can contain up to 128 characters.

Example

cURL request example

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1*****803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&body=abc' 'https://api.netease.im/nimserver/msg/delMsgOneWay.action'

Example success response

HTTP response in JSON

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

Example error response

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

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 -
Was this page helpful?
Yes
No
  • Recall messages
  • Rate limit
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Recall a message for the current user
  • Overview
  • Rate limit
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code