消息路由

消息路由决定一条消息发布后走哪些通道：在线会话直投、离线队列、推送 webhook、应用回调。控制台没有单独的“路由规则表”写接口；真实可配置点是服务开通、功能开关、回调同步决策与推送 webhook，路由结果可在消息轨迹中观察。

概念​

阶段行为可配置点
1. 鉴权与校验AppKey 签名、服务开通、封禁/禁言、内容大小/敏感词服务开通、功能开关、敏感词
2. 入库消息写入应用消息池并分配 seq不可配置
3. 同步回调message.publish.before 决策 pass/replace/block回调 syncEnabled/syncDefaultAction
4. 在线投递向接收方所有 WS 会话推送；deliveredSessions 计数不可配置
5. 离线全部离线时进入离线队列，上限每会话 500 条不可配置
6. 推送按应用推送 webhook 投递离线通知推送配置 webhookUrl/enabled
7. 事件回调message.routed/message.offline 等异步回调回调 events/retry
  • 路由状态在 GET /apps/{appkey}/messages/{messageId}/trace 中可见：stored/delivered/offline_queued/routed/failed。
  • message_routing 是预留 ServiceKey，当前服务端没有读取它；路由由服务开通、回调同步与推送配置共同决定。
  • 推送厂商通道（APNs/FCM/华为等）只做了配置存储，真实发送仍走 webhook；通道测试如实返回 implemented=false。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#apiconfig（tab #apiconfig：服务与 API 配置）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 确认路由前提

    检查服务开通、功能开关、用户封禁/禁言与接收方在线状态。

  2. 配置同步决策（可选）

    需要发送前风控时启用 syncEnabled，并明确超时默认动作。

  3. 配置离线通道

    有离线通知需求时配置推送 webhook；厂商通道配置不等于真实下发。

  4. 用轨迹验证

    发一条测试消息，读 trace 的 status、offlineQueued、callbackDeliveries。

参数表​

配置点方法与路径关键字段
服务开通GET/POST /api/admin/apps/{appkey}/servicesmessage_routing、callbacks、system_notification
功能开关GET/POST /api/admin/apps/{appkey}/featuresfriend/group/chatroom/push/sensitiveWord/messageCallbacks
回调同步GET/POST /api/admin/apps/{appkey}/callbackssyncEnabled、syncTimeoutMs、syncDefaultAction
推送GET/POST /api/admin/apps/{appkey}/pushwebhookUrl、enabled
轨迹GET /api/admin/apps/{appkey}/messages/{messageId}/trace—

示例​

查看路由相关配置​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/services" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/features" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/callbacks" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/push" \
  -H 'X-Admin-Secret: dev-admin'

启用发送前同步拦截​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/callbacks" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"enabled":true,"url":"https://example.com/im/callback","events":["message.publish.before"],"syncEnabled":true,"syncTimeoutMs":500,"syncDefaultAction":"pass"}'

常见问题​

能按群/用户配置不同路由吗？​

不能。路由是应用级行为；差异化请在应用服务器或同步回调中实现。

离线队列满了会怎样？​

每会话离线队列上限 500 条，超出后最旧消息被淘汰；客户端上线只补发仍在队列中的消息。

为什么配置了厂商推送却没收到？​

厂商通道当前只存储配置，没有下发实现；真实离线通知走推送 webhook。

trace 的 routed 和回调成功是一回事吗？​

不是。routed 表示路由完成；回调是否成功看 callbackDeliveries 的响应码。

相关链接​