撤回消息

1. 接口定位

• 接口名称: 撤回消息
• 所属域: msg
• 业务目标: 按会话 ID + 消息序号撤回指定消息

2. 请求定义

• Method: POST
• Path: /msg/revoke_msg
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 条件幂等（重复撤回同一消息会返回“已撤回”）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
conversationID	是	string	会话 ID
seq	是	int64	目标消息序号，必须 >= 0
userID	是	string	操作用户 ID

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

• 成功时为空对象或 null。

5. 业务规则

• 必须通过 userID 权限校验（普通用户或应用管理员）。
• 单聊中通常由发送者撤回；群聊中群主/管理员可按角色规则撤回他人消息。
• 目标消息不存在或已撤回时会返回对应错误。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数缺失（如 userID/conversationID）或 seq 非法	ArgsError
1002	无权限撤回（如普通成员越权）	NoPermissionError
1004	消息不存在	RecordNotFoundError
1404	消息已撤回	MsgAlreadyRevoke
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/msg/revoke_msg", {
  method: "POST",
  headers: {
    operationID: "744dd8c4-29f1-48e2-ad44-66f65158d8db",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversationID: "si_u_1001_u_1002",
    seq: 1024,
    userID: "u_1001"
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "conversationID": "si_u_1001_u_1002",
  "seq": 1024,
  "userID": "u_1001"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例

{
  "errCode": 1404,
  "errMsg": "MsgAlreadyRevoke",
  "errDlt": "msg already revoke"
}

8. 时序流程

1. 校验参数与 userID 访问权限。
2. 按 conversationID + seq 定位消息。
3. 写入撤回标记并广播撤回通知。

9. 变更记录

• 2026-04-09: 首版补充文档发布。