撤回消息和单向删除会话

大约 6 分钟

撤回消息和单向删除会话

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

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

撤回消息

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

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。
toString要撤回消息的接收方。
- 单聊为接收方用户 ID;
- 群聊为群组 ID;
- 聊天室聊天为聊天室 ID。
若不传入该参数,请求失败。
chat_typeString要撤回消息的会话类型:
- chat:单聊;
- groupchat:群聊 ;
- chatroom:聊天室 。
fromString消息撤回方的用户 ID。若不传该参数,默认为 admin
forceBool是否支持撤回超过服务器存储时长的消息。
- true:是。这种情况下,你可以撤回在撤回时长内的消息,也可以撤回超过服务器存储时长的消息。对于后者,该接口会撤回接收方在本地保存的消息。若消息发送的时间介于你的撤回时长和服务器存储时长之间,则撤回失败。例如,如果消息的撤回时长为 2 分钟,在服务器上的存储时长为 7 天,你可以撤回 2 分钟以内发送的消息或发送时间超过 7 天的消息;若消息发送了 3 分钟,则撤回失败。
- false:否,不支持撤回超过服务器存储时长的消息。如果你采用默认的 2 分钟撤回时长或联系了商务设置了撤回时长,服务器只能撤回指定时长内发送的消息,超过该时长的消息无法撤回。例如,你设置的撤回时长为 3 分钟,若消息发送了 4 分钟,则撤回失败。

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

响应示例

撤销成功:

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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
resultString删除结果,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"
}
上次编辑于: