API 参考
圈组

消息撤回

更新时间: 2024/07/17 17:57:34

网易云信服务端 API 支持单向和双向撤回已发送的消息。单聊和群聊消息撤回的区别:

  • 单聊:只能撤回自己发送的消息。
  • 群聊:普通群成员只能撤回自己发送的消息。客户端SDK支持管理员撤回其他群成员的消息(服务端API不支持)。

本文介绍如下两个服务端 API:

双向撤回

功能描述

可双向撤回一定时间内(默认 2 分钟,可在云信控制台配置)的单聊消息与群聊消息。撤回之后,消息接收者和发送者都将收到一条消息撤回通知,并删除对应的离线消息、漫游消息和历史消息。

您可登录云信控制台,并选择应用,然后进入IM 即时通讯 > 功能配置 > 基础功能 > 消息撤回时长配置 IM 消息的可撤回时长,最长可配置604800秒(7天)。

API 使用限制

  • 单个应用最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
  • 下列情况不能撤回:消息为空;消息没有发送成功。
  • 如果账号已经退群或者被踢,尝试撤回群消息时,会返回 {"desc": "not allow!", "code": 403}。 但是在可撤回时长范围内,仍然可以通过以下方式撤回其消息:
    • 调用服务端API单向撤回消息(要求客户端 SDK 版本为7.2.0及以上才能响应撤回)。
    • 通过管理员账号调用客户端 SDK API 撤回普通群成员发送过的消息。
  • 如果消息被反垃圾(即内容审核)命中,尝试撤回时,将报错(状态码:414)。

    上述为实时(同步)的内容审核场景,不支持撤回操作。若采用异步内容审核方案,支持应用服务端根据审核结果对消息进行处理(如撤回)。内容审核的具体内容请参考安全通

  • 如果撤回的消息不存在(deleteMsgidfromto等参数不正确),会按撤回成功处理,返回 200。 :::

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考API调用方式

  • POST 请求中 Body 的设置如下:

参数类型必填说明
deleteMsgid Long 要撤回消息的消息 ID
timetag Long 要撤回消息的创建时间(创建时间为云信服务端生成的消息发送时间戳),示例:"12514613452"
type int 只能传入 7 或 8:
  • 7 表示单聊消息撤回
  • 8 表示群消息撤回

传入其他值都将报错
from String 消息发送方的云信 IM 账号(accid)
to String 如果是单聊消息,为消息接收方的云信 IM 账号(accid)。如果是群消息,则为对应群的ID (tid)
msg String 消息撤回的相应描述,默认值为“撤回了一条信息”。最大长度 128 个字符
ignoreTime String 只能传入 1,1 表示忽略撤回时间检测,传其他值均判定为非法参数。如果传入 1,最多撤回最近 30 天内的消息。如果需要撤回时间检测,不填即可。
pushcontentString推送文案,Android 以此为推送显示文案;iOS 若未填写 payload,显示文案以 pushcontent 为准。超过 500 字符后,会对文本进行截断
payloadString推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置
env String 消息撤回事件需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称(如下图),最大 32 个字符

自定义抄送环境.png

attachString扩展字段,最大 5000 字符

示例

cURL请求示例

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'

请求成功返回示例

http 响应:json

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

请求失败返回示例

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

状态码

该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码

如果 deleteMsgid、from、to 等参数不正确(即对应消息不存在的情况下),该接口将直接返回 200,按撤回成功处理。

状态码 说明 处理建议
403 导致请求失败的原因可能为:
  • 接口鉴权失败
  • 消息不允许撤回
查看对应提示信息做出处理
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 频控限制,访问频率过高 降低访问频率
500 服务出错 -

单向撤回

功能描述

可单向撤回单聊消息和群消息。撤回之后,消息接收者会收到一条单向撤回的通知,并删除对应的离线消息、漫游消息、历史消息;撤回之后,消息发送者无感知,可以正常使用漫游消息、历史消息。

此接口最长撤回 30 天内的消息(不受控制台消息撤回时长限制)。

API 使用限制

  • 单个应用最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。
  • 下列情况不能撤回:消息为空;消息没有发送成功;消息接收者是自己。
  • 如果消息被反垃圾(即内容审核)命中,尝试撤回时,将报错(状态码:414)。

    上述为实时(同步)的内容审核场景,不支持撤回操作。若采用异步内容审核方案,支持应用服务端根据审核结果对消息进行处理(如撤回)。内容审核的具体内容请参考安全通

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考API调用方式

  • POST 请求中 Body 的设置如下:

参数类型必填说明
deleteMsgid Long 要撤回消息的消息 ID
timetag long 待撤回消息的创建时间(创建时间为云信服务端生成的消息发送时间戳),示例:"12514613452"
type int 待撤回消息的类型,只能传入 13 或 14。13 表示点对点消息撤回,14 表示群消息撤回,传入其他值均判定为参数错误
from String 消息发送者的云信 IM 账号(accid)
to String 消息接收方。如果待撤回消息为单聊消息,则需传入消息接收者的云信 IM 账号(accid)。如果是群消息,则需传入对应群的ID (tid)
msg String 消息撤回的相应描述,默认值为“撤回了一条信息”。最大长度 128 个字符

示例

cURL请求示例

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

请求成功返回示例

http 响应:json

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

请求失败返回示例

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

状态码

该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码

状态码 说明 处理建议
403 导致请求失败的原因可能为:
  • 接口鉴权失败
  • 消息不允许撤回
查看对应提示信息做出处理
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 频控限制,访问频率过高 降低访问频率
500 服务出错 -
此文档是否对你有帮助?
有帮助
去反馈
  • 双向撤回
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码
  • 单向撤回
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码