撤回消息

大约 9 分钟

撤回消息

你一次可以撤回发送成功的单条或多条消息,包括客户端发送的消息以及通过 RESTful API 发送的消息。调用 RESTful API 撤回消息后,服务端的消息(历史消息,离线消息或漫游消息)以及消息发送方和接收方的内存和数据库中的消息均会撤销。

默认情况下,发送方可撤回发出 2 分钟内的消息。你可以在环信即时通讯云控制台open in new window功能配置 > 功能配置总览 > 基础功能 页面设置消息撤回时长,该时长不超过 7 天。

对于附件类型消息,包括图片、音频和视频和文件消息,撤回消息后,消息附件也相应删除。

前提条件

要调用环信即时通讯 RESTful API,请确保满足以下要求:

公共参数

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息

响应参数

参数类型描述
actionString请求方法。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
uriString请求 URL。
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
timestampLongHTTP 响应的 Unix 时间戳,单位为毫秒。
durationInt从发送 HTTP 请求到响应的时长,单位为毫秒。

认证方式

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式,详见 使用 App Token 鉴权

撤回单条消息

发送方可以撤回一条发送成功的消息。

调用频率上限:100 次/秒/App Key

HTTP 请求

POST https://{host}/{org_name}/{app_name}/messages/msg_recall
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
msg_idString要撤回消息的消息 ID。由于每次只能撤销一条消息,因此只能传入一个消息 ID。
toString要撤回消息的接收方。
- 单聊为接收方用户 ID;
- 群聊为群组 ID;
- 聊天室聊天为聊天室 ID。
若不传入该参数,请求失败。
chat_typeString要撤回消息的会话类型:
- chat:单聊;
- groupchat:群聊 ;
- chatroom:聊天室 。
fromString消息撤回方的用户 ID。若不传该参数,默认为 admin
sync_deviceBool是否支持单聊消息撤回同步给消息发送方的所有在线设备:
- (默认) true:是;
- false:否。

提示

当参数 force 设置为 true 且消息已过期,此时若要将消息撤回同步发送方,则需将 from 参数设置为消息发送方。

forceBool是否支持强制撤回消息。
- true:是。这种情况下,无论消息是否过期,你都可以撤回。若需撤回已过期的消息,force 须设置为 true
- (默认)false:否。这种情况下,你只能在撤回时长内撤销服务端存在的消息。
recallMessageExtensionInfoString消息撤回相关的扩展信息。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
msg_idString需要撤回的消息 ID。
recalledString消息撤回结果,成功是 yes
fromString消息撤回方的用户 ID。
toString撤回消息的送达方。
- 单聊为送达方用户 ID;
- 群聊为群组 ID;
- 聊天室聊天为聊天室 ID。
chattypeString撤回消息的会话类型:
- chat:单聊;
- groupchat:群聊;
- chatroom:聊天室。

其他参数及说明详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H "Authorization: Bearer <YourAppToken>"
"https://XXXX/XXXX/XXXX/messages/msg_recall"
-d '{
    "msg_id": "1028442084794698104",
    "to": "user2",
    "from": "user1",
    "chat_type": "chat",
    "force": true,
    "recallMessageExtensionInfo": "{\"type\": \"chat\"}"
}'
响应示例
{
  "path": "/messages/msg_recall",
  "uri": "https://XXXX/XXXX/XXXX/messages/msg_recall",
  "timestamp": 1657529588473,
  "organization": "XXXX",
  "application": "09ebbf8b-XXXX-XXXX-XXXX-d47c3b38e434",
  "action": "post",
  "data": {
    "recalled": "yes",
    "chattype": "chat",
    "from": "XXXX",
    "to": "XXXX",
    "msg_id": "1028442084794698104"
  },
  "duration": 8,
  "applicationName": "XXXX"
}

错误码

如果返回的 HTTP 状态码非 200,表示请求失败,可能提示以下错误码:

HTTP 状态码错误类型错误提示可能原因处理建议
400message_recall_errorparam msg_id can't be empty请求参数 msg_id 是空字符串。输入正确的请求参数 msg_id
400message_recall_errorparam to can't be empty请求参数 to 是空字符串。输入正确的请求参数 to
400message_recall_errorparam chat_type can't be empty请求参数 chat_type 是空字符串。输入正确的请求参数chat_type
400message_recall_errorparam force can't be empty请求参数 force 是空。输入正确的请求参数 force
400message_recall_errorcan’t find msg to未找到撤回消息的接收⽅。需传入正确的消息接收方。
403message_recall_errorexceed recall time limit消息撤回超时。消息撤回时长默认为消息发送后的 2 分钟。
403message_recall_errornot_found msg消息因过期在服务端删除或消息已被撤回。若撤回过期的消息,你需要开启强制撤回,即将 force 设置为 true。这种情况下,会撤回接收方在本地保存的消息,但发送方本地消息仍存在。
若消息已被撤回,则无需重复撤回。
403forbidden_opmessage recall service is unopened消息撤回服务未在环信即时通讯云管理后台开通。请先在环信即时通讯云管理后台开通该服务。
500internal error后端服务出现异常。

例如,消息撤回服务未在环信即时通讯云管理后台开通,返回示例如下:

{
  "error": "forbidden_op",
  "exception": "EasemobForbiddenOpException",
  "timestamp": 1644402553845,
  "duration": 0,
  "error_description": "message recall service is unopened"
}

关于其他错误,你可以参考 响应状态码 了解可能的原因。

批量撤回消息

你一次可撤回多条消息,每次可同时撤回单聊、聊天室或群组聊天的多条消息。

调用频率上限:100 次/秒/App Key

HTTP 请求

POST https://{host}/{org_name}/{app_name}/messages/batch_recall
路径参数

参数及描述详见 公共参数

请求 header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
msgsJSON Array要撤回的消息的详情。单次请求最多可撤回 30 条消息。
- msg_idString要撤回消息的消息 ID。
- toString要撤回消息的接收方。
- 单聊为接收方的用户 ID;
- 群聊为群组 ID;
- 聊天室聊天为聊天室 ID。
若不传入该参数,请求失败。
- fromString消息撤回方的用户 ID。若不传该参数,默认为 admin
- chat_typeString要撤回消息的会话类型:
- chat:单聊;
- groupchat:群聊 ;
- chatroom:聊天室 。
- sync_deviceBool是否支持单聊消息撤回同步给消息发送方的所有在线设备:
- (默认) true:是;
- false:否。

提示

当参数 force 设置为 true 且消息已过期,此时若要将消息撤回同步发送方,则需将 from 参数设置为消息发送方。

- forceBool是否支持强制撤回消息。
- true:是。这种情况下,无论消息是否过期,你都可以撤回。若需撤回已过期的消息,force 须设置为 true
- (默认)false:否。这种情况下,你只能在撤回时长内撤销服务端存在的消息。
recallMessageExtensionInfoString消息撤回相关的扩展信息。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体的 data 中包含以下字段:

参数类型描述
msg_idString需要撤回的消息 ID。
recalledString消息撤回结果,成功是 yes
fromString消息撤回方的用户 ID。
toString撤回消息的送达方。
- 单聊为送达方用户 ID;
- 群聊为群组 ID;
- 聊天室聊天为聊天室 ID。
chattypeString撤回消息的会话类型:
- chat:单聊;
- groupchat:群聊;
- chatroom:聊天室。

其他参数及说明详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 响应状态码 了解可能的原因。

示例

请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST --location "https://XXXX/XXXX/XXXX/messages/batch_recall" \
-H 'Authorization: Bearer <YourAppToken>'  \
-H 'Content-Type: application/json'  \
-H 'Accept: application/json'  \
-d '{
  "msgs": [
   {
    "msg_id": "7126XXXX2581", 
    "to": "d95XXXX81c64",      
    "from": "18XXXXebf262",   
    "chat_type": "chatroom",
    "force": false,
    "sync_device": false
    },
    {
    "msg_id": "10436XXXX4564398104",
    "to": "d9571XXXXc64",
    "from": "18e4XXXXf262",
    "chat_type": "chat",
    "force": false,
    "sync_device": false
    }
  ]
}'
响应示例
{
  "path": "/messages/batch_recall",
  "uri": "https://XXXX/XXXX/XXXX/messages/batch_recall",
  "timestamp": 1657529588473,
  "organization": "XXXX",
  "application": "09ebbf8b-XXXX-XXXX-XXXX-d47c3b38e434",
  "action": "post",
  "data": [
    {
      "recalled": "yes",
      "chattype": "chat",
      "from": "XXXX",
      "to": "XXXX",
      "msg_id": "1028442XXXX94698104"
    },
    {
      "recalled": "yes",
      "chattype": "chat",
      "from": "XXXX",
      "to": "XXXX",
      "msg_id": "104367XXXX564398104"
    }
  ], 
  "duration": 8,
  "applicationName": "XXXX"
}

错误码

详见撤回单条消息