撤回消息和单向删除会话

你可以撤回发送的消息，包括客户端发送的消息以及通过 RESTful API 发送的消息。调用 RESTful API 撤回消息后，该条消息的离线存储、漫游存储以及消息发送方和接收方的客户端的本地缓存都会被撤回。

此外，你也可以从服务器中单向删除会话，并且设置是否删除该会话在服务端的漫游消息。

撤回消息

发送方可以撤回一条发送成功的消息。默认情况下，发送方可撤回发出 2 分钟内的消息。你可以在 环信即时通讯云控制台的服务管理 > 服务概览 页面设置消息撤回时长，该时长不超过 7 天。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/messages/msg_recall

路径参数

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

请求 header

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

请求 body

参数	类型	是否必需	描述
msg_id	String	是	要撤回消息的消息 ID。
to	String	是	要撤回消息的接收方。 - 单聊为接收方用户 ID； - 群聊为群组 ID； - 聊天室聊天为聊天室 ID。 若不传入该参数，请求失败。
chat_type	String	是	要撤回消息的会话类型： - chat：单聊； - groupchat：群聊 ； - chatroom：聊天室 。
from	String	否	消息撤回方的用户 ID。若不传该参数，默认为 admin。
force	Bool	是	是否支持撤回超过服务器存储时长的消息。 - true：是。这种情况下，你可以撤回在撤回时长内的消息，也可以撤回超过服务器存储时长的消息。对于后者，该接口会撤回接收方在本地保存的消息。若消息发送的时间介于你的撤回时长和服务器存储时长之间，则撤回失败。例如，如果消息的撤回时长为 2 分钟，在服务器上的存储时长为 7 天，你可以撤回 2 分钟以内发送的消息或发送时间超过 7 天的消息；若消息发送了 3 分钟，则撤回失败。 - false：否，不支持撤回超过服务器存储时长的消息。如果你采用默认的 2 分钟撤回时长或联系了商务设置了撤回时长，服务器只能撤回指定时长内发送的消息，超过该时长的消息无法撤回。例如，你设置的撤回时长为 3 分钟，若消息发送了 4 分钟，则撤回失败。

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/XXXX/XXXX/messages/msg_recall"
-d '{
    "msg_id": "1028442084794698104",
    "to": "user2",
    "from": "user1",
    "chat_type": "chat",
    "force": true
}'

响应示例

撤销成功：

{
  "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"
}

撤销失败：

recalled：消息撤销失败包含以下几种情况：

• ”can’t find msg to”：未找到撤回消息的接收⽅；
• ”exceed recall time limit”：消息撤回超时；
• ”not_found msg”：消息过期或已被撤回；
• ”internal error”：后端服务出现异常。

{
  "msgs": [{ "msg_id": "673296835082717140", "recalled": "not_found msg" }]
}

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

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

单向删除会话

该方法使聊天用户能够从服务器中删除会话。删除会话后，该用户将从服务器获取不到该会话。该会话的其他参与聊天用户仍然可以从服务器获取会话内容。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/users/{username}/user_channel

路径参数

参数	类型	是否必需	描述
username	String	是	要删除会话的用户的唯一标识符，即用户 ID。

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

请求 header

参数	类型	是否必需	描述
Authorization	String	是	App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

请求 body

参数	类型	是否必需	描述
channel	String	是	要删除的会话 ID。该参数的值取决于会话类型 type 的值: - type 为 chat，即单聊时，会话 ID 为对端用户 ID； - type 为 groupchat，即群聊时，会话 ID 为群组 ID。
type	String	是	会话类型。 - chat：单聊会话； -groupchat：群聊会话。
delete_roam	Bool	是	是否删除该会话在服务端的漫游消息。 - true：是。若删除了该会话的服务端消息，则用户无法从服务器拉取该会话的漫游消息。 - false：否。用户仍可以从服务器拉取该会话的漫游消息。

HTTP 响应

响应 body

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

字段	类型	描述
result	String	删除结果，ok 表示成功，失败则直接返回错误码和原因。

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

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

示例

请求示例

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

curl -X DELETE -H "Authorization: Bearer <YourAppToken>" "https://XXXX/XXXX/XXXX/users/u1/user_channel" -d '{"channel":"u2", "type":"chat"，"delete_roam": true}'

响应示例

{
  "path": "/users/user_channel",
  "uri": "https://XXXX/XXXX/XXXX/users/u1/user_channel",
  "timestamp": 1638440544078,
  "organization": "XXXX",
  "application": "c3624975-XXXX-XXXX-9da2-ee91ed4c5a76",
  "entities": [],
  "action": "delete",
  "data": {
    "result": "ok"
  },
  "duration": 3,
  "applicationName": "XXXX"
}