OpenIM 回调

1. 接口定位

• 接口名称: OpenIM 回调
• 所属域: client/callback
• 业务目标: 接收 OpenIM Server Webhook 事件并转发到 chat 服务内部处理
• 面向对象: OpenIM Server，不面向普通客户端

2. 请求定义

• Method: POST
• Path: /callback/open_im
• Content-Type: 由 OpenIM 回调方决定，服务端直接读取原始请求体
• operationID: 建议通过 Header operationID 传入
• 鉴权: 无额外业务 token；安全控制应在网关或网络层完成

3. 请求参数

Query 参数

字段	必填	类型	说明
command	是	string	OpenIM 回调命令类型

Body 参数

• 请求体按原始字符串读取，再由 chat 服务按 command 进行反序列化。

当前已实现命令：

command	说明
callbackBeforeAddFriendCommand	加好友前校验目标用户是否允许被添加

4. 处理规则

• API 层不会解析业务字段，只会读取原始 body 并转发给 chat 服务。
• chat 服务当前仅处理“加好友前校验”命令：
  • 读取 toUserID
  • 查询目标用户资料
  • 检查 allowAddFriend
  • 若不允许添加，返回拒绝错误
• 未实现的 command 会直接返回参数错误。

5. 错误码与失败场景

错误码	场景	典型报错
1001	command 不支持	invalid command ...
1001	回调 body JSON 解析失败	由 JSON 反序列化错误返回
-	目标用户不存在或查询失败	由数据库查询链路返回
20014	目标用户不允许被添加好友	RefuseFriend

6. 示例

请求示例

POST /callback/open_im?command=callbackBeforeAddFriendCommand
Content-Type: application/json

{
	"callbackCommand": "callbackBeforeAddFriendCommand",
	"fromUserID": "u_1001",
	"toUserID": "u_1002",
	"reqMsg": "加个好友",
	"operationID": "openim-callback-001"
}

成功响应示例

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

7. 变更记录

• 2026-03-31: 调整为简要内部文档，仅说明已实现的 OpenIM webhook 行为。