OpenIM 回调

1. 接口定位

• 接口名称: OpenIM 回调
• 所属域: chat/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	加好友前校验目标用户是否允许被添加
callbackBeforeSendSingleMsgCommand	单聊发送前违禁词检测（阶段1）
callbackBeforeSendGroupMsgCommand	群聊发送前违禁词检测（阶段1）

4. 处理规则

• API 层不会解析业务字段，只会读取原始 body 并转发给 chat 服务。
• chat 服务当前处理以下 before 命令：
  • callbackBeforeAddFriendCommand：校验目标用户是否允许被添加好友。
  • callbackBeforeSendSingleMsgCommand：按 single 场景策略执行违禁词拦截。
  • callbackBeforeSendGroupMsgCommand：按 group 场景策略执行违禁词拦截。
• 未实现的 command 会直接返回参数错误。

回调响应语义（before 命令）

• OpenIM Server before 回调基于 actionCode + nextCode + errCode 判断是否拦截。
• 当 before 检查未命中或允许放行时，返回：
  • actionCode = 0
  • nextCode = 0
  • errCode = 0
• 当 before 检查命中并拒绝时，返回：
  • actionCode = 0
  • nextCode = 1
  • errCode = 20016（SensitiveWordBlocked）

5. 错误码与失败场景

错误码	场景	典型报错
1001	command 不支持	invalid command ...
1001	回调 body JSON 解析失败	由 JSON 反序列化错误返回
-	目标用户不存在或查询失败	由数据库查询链路返回
20014	目标用户不允许被添加好友	RefuseFriend
20016	发送前命中违禁词并拒绝	sensitive word detected

6. 示例

请求示例

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

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

成功响应示例

{
  "actionCode": 0,
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "nextCode": 0
}

拦截响应示例（before 命令）

{
  "actionCode": 0,
  "errCode": 20016,
  "errMsg": "sensitive word detected",
  "errDlt": "sensitive word detected",
  "nextCode": 1
}

7. 变更记录

• 2026-03-31: 调整为简要内部文档，仅说明已实现的 OpenIM webhook 行为。
• 2026-07-13: 新增 beforeSendSingleMsg/beforeSendGroupMsg 违禁词拦截命令说明，补充 before 回调响应语义。