服务端 API

发送业务通知

发送业务通知 用于让外部业务服务通过 OpenIM 向客户端实时传递业务事件。OpenIM 在这里作为业务系统与客户端之间的消息传递中间件：业务服务只需要调用一次接口，OpenIM 负责将通知路由到指定的单聊或群聊，客户端通过 OnRecvCustomBusinessMessage 回调接收并处理。

它适合承载订单状态、审核结果、运营指令、业务数据同步信号等不需要由 OpenIM 解析的自定义事件。key 用于标识事件类型，data 由业务方定义格式；客户端收到的 sendMsg 字段会反映本次通知是否同时作为消息写入会话。

这不是普通聊天消息接口。业务服务调用后，客户端不会通过普通文本消息回调处理，而是通过 SDK 的 OnRecvCustomBusinessMessage 接收业务通知；业务方应在客户端注册对应监听器，并自行解析 data。

请先在接入准备中配置 API 地址和 Token；接口参数通过请求头和 JSON 请求体传递。

HTTP 请求

POST {API_ADDRESS}/msg/send_business_notification

请求示例

curl --request POST "${API_ADDRESS}/msg/send_business_notification" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "key": "order_paid",
  "data": "{\"orderID\":\"order_001\"}",
  "sendUserID": "openIMAdmin",
  "recvUserID": "user_001",
  "sendMsg": true,
  "reliabilityLevel": 1
}'

安全提示：管理员 Token 只能保存在业务服务端或 OpenIM Chat 服务端，不能下发到客户端或写入前端代码。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递业务参数。

请求头

Header	是否必填	类型	说明
operationID	是	string	每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token	是	string	APP 管理员 Token；仅保存在业务服务端或 OpenIM Chat 服务端。
Content-Type: application/json	是	string	请求体为 JSON 时必须设置。

请求体

{
  "key": "order_paid",
  "data": "{\"orderID\":\"order_001\"}",
  "sendUserID": "openIMAdmin",
  "recvUserID": "user_001",
  "sendMsg": true,
  "reliabilityLevel": 1
}

参数名	是否必填	类型	说明
key	否	string	业务事件类型或业务通知分类。建议使用稳定、可向后兼容的事件名，例如 `order_paid`。
data	否	string	业务通知数据字符串。格式由业务方约定，通常传入 JSON 字符串；客户端会在 `OnRecvCustomBusinessMessage` 回调中自行解析。
sendUserID	是	string	发送者用户 ID。通常使用业务通知专用账号或 APP 管理员账号。
recvUserID	与 `recvGroupID` 二选一	string	单聊接收者用户 ID。与 `recvGroupID` 不能同时为空或同时设置。
recvGroupID	与 `recvUserID` 二选一	string	群聊接收者群组 ID。与 `recvUserID` 不能同时为空或同时设置。
sendMsg	否	boolean	是否同时将业务通知作为消息写入会话。默认值由服务端通知配置决定；设为 `true` 时，通知会产生对应的单聊或群聊消息。
reliabilityLevel	否	int	通知消息的可靠性等级，参见下方枚举。未传时默认为 `1`。

reliabilityLevel

值	名称	说明
`1`	`UnreliableNotification`	在线推送。客户端在线时实时触发业务通知回调；客户端离线期间的通知不会在重连或重新登录后补发。默认值。
`2`	`ReliableNotificationNoMsg`	必达通知。客户端断线重连或重新登录后仍会同步并触发业务通知回调，适用于通知必须送达的场景。该等级不产生普通会话消息。

reliabilityLevel: 2 的通知会按顺序进行全量同步。不要使用该等级高频或批量发送大量通知，否则积压的必达通知会延长客户端断线重连、重新登录及消息同步所需的时间，影响客户端消息同步性能。

可靠性等级描述的是 OpenIM 对通知的投递处理方式，不代表客户端业务处理一定成功。对于必须完成的业务动作，仍建议在 data 中携带唯一事件 ID，并在客户端实现幂等处理和必要的业务确认机制。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "serverMsgID": "server_msg_001",
    "clientMsgID": "client_msg_001",
    "sendTime": 1719800000000,
    "modify": null
  }
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，0 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。
data	object	接口返回数据。
data.serverMsgID	string	服务端消息 ID。
data.clientMsgID	string	客户端消息 ID。
data.sendTime	int	消息发送时间，Unix 毫秒时间戳。
data.modify	object	回调或服务端逻辑修改后的消息数据，可能为空。

客户端接收流程

业务服务端调用本接口，指定 recvUserID 或 recvGroupID。
OpenIM 将业务通知路由到目标用户或群组；如果 sendMsg 为 true，同时在对应会话中产生消息。
客户端 SDK 触发 OnRecvCustomBusinessMessage 回调。
客户端从回调数据中读取业务通知内容，按 key 分发事件，并解析 data。

客户端收到的业务通知内容由业务方定义。建议在 data 中包含唯一事件 ID、事件版本和必要的业务数据，客户端按事件 ID 做幂等处理，并为未知 key 保留兼容逻辑。

使用建议

业务通知适合承载订单状态、审核结果、系统事件和实时同步信号等轻量业务数据。如果业务事件需要在聊天窗口中作为普通消息展示，将 sendMsg 设为 true；如果只需要触发客户端业务回调而不希望增加会话消息，则使用 sendMsg: false，并根据场景选择合适的 reliabilityLevel。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

错误场景	可能原因	处理方式
鉴权失败	`token` 缺失、过期，或调用账号没有该接口权限。	重新获取有效 Token，并在可信后端调用接口。
链路追踪困难	`operationID` 缺失或在大量请求中重复使用。	为每次请求生成独立 `operationID`，并在服务端日志中保留。
参数校验失败	请求体字段类型、必填字段或消息内容结构不符合接口要求。	对照请求体参数表和限制说明检查字段。

权限和限制

通过 OpenIM 向单聊或群聊客户端传递业务通知，并触发 OnRecvCustomBusinessMessage 回调。
必须使用 APP 管理员 Token 调用。
sendUserID 必填，recvUserID 和 recvGroupID 必须二选一。
sendMsg 决定是否同时产生会话消息，不决定客户端是否触发业务通知回调。
key 建议使用稳定的业务事件名，data 建议使用带版本的 JSON 字符串并保持向后兼容。
reliabilityLevel 未传时使用 1。只有确实需要客户端断线后补发的事件才应使用 2，并严格控制发送量。
必达通知采用顺序全量同步，发送过多会影响客户端重连、登录和消息同步性能。
可靠性等级不能替代业务幂等和业务状态确认。