消息追踪

消息追踪用于回答“这条消息去哪了”：按用户、会话、时间或关键字检索落盘消息，再用轨迹接口查看 stored/delivered/offline_queued/routed/failed、在线投递会话数、离线待补发与关联回调投递结果。

概念​

轨迹状态含义
stored已入库，但尚未完成在线投递/路由
delivered已投递到至少一个在线会话（deliveredSessions 为会话数）
offline_queued接收方全部离线，进入离线队列等待补发
routed已完成应用回调/消息路由
failed投递失败（含回调失败等）
  • 聊天室消息是 ephemeral 广播，不落盘，因此检索与轨迹都查不到。
  • 轨迹返回 callbackDeliveries，可直接看到回调事件、响应码与重试结果。
  • 控制台支持以指定用户/系统身份补发消息（admin.messages.send），用于联调与补偿。

前置条件​

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

步骤​

  1. 缩小检索范围

    优先用 messageId 查轨迹；没有 ID 时按 userId + conversationType + targetId 或时间范围检索。

  2. 读轨迹

    看 status、deliveredSessions、offlineQueued、routed 与 ackAt。

  3. 定位回调问题

    若 routed=false 或回调失败，展开 callbackDeliveries 或到「回调服务」查投递日志。

  4. 必要时补发

    用 admin.messages.send 以系统/指定用户身份发送；补发是新消息，不改变原消息状态。

参数表​

操作方法与路径参数
消息检索GET /api/admin/apps/{appkey}/messagesuserId、conversationType、targetId、keyword、from、to、offset、limit
投递轨迹GET /api/admin/apps/{appkey}/messages/{messageId}/trace—
补发消息POST /api/admin/apps/{appkey}/messages{from,conversationType,targetId,content}
导出 CSVGET /api/admin/apps/{appkey}/messages/exportlimit、beforeSeq

示例​

按用户检索并查轨迹​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/messages?userId=alice&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

# 用返回的 messageId
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/messages/m_1001/trace" \
  -H 'X-Admin-Secret: dev-admin'

以系统身份补发一条文本​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/messages" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"from":"system","conversationType":1,"targetId":"alice","content":{"type":"text","text":"补偿通知：请重新登录"}}'

常见问题​

聊天室消息为什么查不到？​

聊天室消息不落盘，只对在线成员广播；需要留痕请用群聊或系统通知。

deliveredSessions 为 0 但有 ackAt？​

可能消息已入库但接收方全部离线；查看 offlineQueued 是否为 true。

补发会改原消息状态吗？​

不会。补发是一条新消息；原消息状态只能通过撤回/修改等业务接口变更。

keyword 搜什么字段？​

对消息文本做包含匹配；非文本消息按类型标记匹配，不解析二进制内容。

相关链接​