撤回消息

大约 9 分钟

撤回消息

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

默认情况下，发送方可撤回发出 2 分钟内的消息。你可以联系声网商务提升消息撤回时长，该时长不超过 7 天。

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

前提条件

要调用即时通讯 RESTful API，请确保满足以下要求：

已在声网控制台open in new window 开通配置即时通讯 IM 服务。
已从服务端获取 app token，详见使用 Token 鉴权。
了解即时通讯 IM API 的调用频率限制，详见接口频率限制。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	即时通讯 IM 分配的用于访问 RESTful API 的域名。
`app_id`	String	是	声网为每个项目自动分配的 App ID，作为项目唯一标识。

响应参数

参数	类型	描述
`action`	String	请求方法。
`uri`	String	请求 URL。
`path`	String	请求路径，属于请求 URL 的一部分，开发者无需关注。
`entities`	JSON	响应实体。
`data`	JSON	实际获取的数据详情。
`created`	Long	群组创建时间，Unix 时间戳，单位为毫秒。
`timestamp`	Long	Unix 时间戳，单位为毫秒。
`duration`	Int	从发送请求到响应的时长，单位为毫秒。
`properties`	String	响应属性。

认证方式

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

Authorization: Bearer YourAppToken

为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 IM RESTful API 推荐使用 app token 的鉴权方式，详见使用 Token 鉴权。

撤回单条消息

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

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

HTTP 请求

POST https://{host}/app-id/{app_id}/messages/msg_recall

路径参数

参数及描述详见公共参数。

参数	类型	是否必需	描述
`Content-Type`	String	是	内容类型。请填 `application/json`。
`Accept`	String	是	内容类型。请填 `application/json`。
`Authorization`	String	是	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。

请求 body

参数	类型	是否必需	描述
`msg_id`	String	是	要撤回消息的消息 ID。由于每次只能撤销一条消息，因此只能传入一个消息 ID。
`to`	String	是	要撤回消息的接收方。 - 单聊为接收方用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。若不传入该参数，请求失败。
`chat_type`	String	是	要撤回消息的会话类型： - `chat`：单聊； - `groupchat`：群聊； - `chatroom`：聊天室。
`from`	String	否	消息撤回方的用户 ID。若不传该参数，默认为 `admin`。
`sync_device`	Bool	否	是否支持单聊消息撤回同步给消息发送方的所有在线设备： - (默认) `true`：是； - `false`：否。提示当参数 `force` 设置为 `true` 且消息已过期，此时若要将消息撤回同步发送方，则需将 `from` 参数设置为消息发送方。
`force`	Bool	否	是否支持强制撤回消息。 - `true`：是。这种情况下，无论消息是否过期，你都可以撤回。若需撤回已过期的消息，`force` 须设置为 `true`。 - （默认）`false`：否。这种情况下，你只能在撤回时长内撤销服务端存在的消息。
`recallMessageExtensionInfo`	String	否	消息撤回相关的扩展信息。

HTTP 响应

响应 body

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

参数	类型	描述
`msg_id`	String	需要撤回的消息 ID。
`recalled`	String	消息撤回结果，成功是 `yes`。
`from`	String	消息撤回方的用户 ID。
`to`	String	撤回消息的送达方。 - 单聊为送达方用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。
`chattype`	String	撤回消息的会话类型： - `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/app-id/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,
  "action": "post",
  "data": {
    "recalled": "yes",
    "chattype": "chat",
    "from": "XXXX",
    "to": "XXXX",
    "msg_id": "1028442084794698104"
  },
  "duration": 8
}

错误码

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

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

例如，消息撤回服务未在声网控制台open in new window开通，返回示例如下：

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

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

批量撤回消息

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

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

HTTP 请求

POST https://{host}/app-id/{app_id}/messages/batch_recall

路径参数

参数及描述详见公共参数。

请求 header

参数	类型	是否必需	描述
`Content-Type`	String	是	内容类型。请填 `application/json`。
`Accept`	String	是	内容类型。请填 `application/json`。
`Authorization`	String	是	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。

请求 body

参数	类型	是否必需	描述
`msgs`	JSON Array	是	要撤回的消息的详情。单次请求最多可撤回 30 条消息。
- `msg_id`	String	是	要撤回消息的消息 ID。
- `to`	String	是	要撤回消息的接收方。 - 单聊为接收方的用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。若不传入该参数，请求失败。
- `from`	String	否	消息撤回方的用户 ID。若不传该参数，默认为 `admin`。
- `chat_type`	String	是	要撤回消息的会话类型： - `chat`：单聊； - `groupchat`：群聊； - `chatroom`：聊天室。
- `sync_device`	Bool	否	是否支持单聊消息撤回同步给消息发送方的所有在线设备： - (默认) `true`：是； - `false`：否。提示当参数 `force` 设置为 `true` 且消息已过期，此时若要将消息撤回同步发送方，则需将 `from` 参数设置为消息发送方。
- `force`	Bool	否	是否支持强制撤回消息。 - `true`：是。这种情况下，无论消息是否过期，你都可以撤回。若需撤回已过期的消息，`force` 须设置为 `true`。 - （默认）`false`：否。这种情况下，你只能在撤回时长内撤销服务端存在的消息。
`recallMessageExtensionInfo`	String	否	消息撤回相关的扩展信息。

HTTP 响应

响应 body

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

参数	类型	描述
`msg_id`	String	需要撤回的消息 ID。
`recalled`	String	消息撤回结果，成功是 `yes`。
`from`	String	消息撤回方的用户 ID。
`to`	String	撤回消息的送达方。 - 单聊为送达方用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。
`chattype`	String	撤回消息的会话类型： - `chat`：单聊； - `groupchat`：群聊； - `chatroom`：聊天室。

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

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

示例

请求示例

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

curl -X POST --location "https://XXXX/app-id/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,
  "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
}

错误码

详见撤回单条消息。

撤回消息

# 撤回消息

# 前提条件

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 撤回单条消息

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 批量撤回消息

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

撤回消息

前提条件

公共参数

请求参数

响应参数

认证方式

撤回单条消息

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

批量撤回消息

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码