系统会话

系统会话是 conversationType=4、targetId=system 的专用会话，用于审核拒绝通知、封禁提示、运营公告等。控制台没有独立的“系统会话”tab；读取走消息检索，发送走 Open API message.system.publish。

概念​

能力入口说明
读取系统通知GET /api/admin/apps/{appkey}/messages?conversationType=4&targetId=system与普通消息同一检索接口
发送系统通知POST /im/v2/message/system/publish（Open API）content.type=system，toUserIds 1–1000
客户端读取RIM.getSystemMessages({limit,beforeSeq})IMLib 固定 SYSTEM 会话
审核拒绝通知审核 reject 自动发送内容为 message.blocked 系统通知
  • 系统通知按用户落盘在系统会话中，未读/已读与普通会话一致。
  • 系统通知不是广播：同一内容发给 N 个用户会产生 N 条用户会话消息（广播/在线广播是另外的接口）。
  • 控制台的 admin.messages.send 可发任意 Content，但系统通知建议用 Open API 的专用接口以保证 systemType 语义。

前置条件​

  • 服务端已启动（默认 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} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。
  • 发送系统通知需应用开通 system_notification 服务。

步骤​

  1. 查看已发送的系统通知

    按 conversationType=4&targetId=system 检索，结合 userId 定位接收者。

  2. 构造系统通知

    Open API 传 toUserIds 与 content:{type:"system",systemType:"system_notification",text:"…"}。

  3. 验签并调用

    应用服务器按 App-Key/Nonce/Timestamp/Signature 签名后 POST；客户端不需要密钥。

  4. 确认到达

    用消息轨迹确认 delivered 或 offline_queued；客户端系统会话应出现未读。

参数表​

操作方法与路径请求体 / 参数
管理端检索GET /api/admin/apps/{appkey}/messagesconversationType=4、targetId=system、userId 等
Open API 发送POST /im/v2/message/system/publish{toUserIds,content,clientMsgId?}
客户端读取RIM.getSystemMessages({limit,beforeSeq})SDK 方法，无 HTTP 参数

示例​

检索某个用户的系统通知​

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

Open API 发送系统通知（应用服务器签名）​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/message/system/publish" \
  -H 'App-Key: demo' \
  -H 'Nonce: 8f3c2a' \
  -H 'Timestamp: 1750000000000' \
  -H 'Signature: <hex(sha1(appSecret+nonce+timestamp))>' \
  -H 'content-type: application/json' \
  -d '{"toUserIds":["alice"],"content":{"type":"system","systemType":"system_notification","text":"您的消息因违规已被屏蔽"}}'

常见问题​

系统会话和广播有什么区别？​

系统会话按用户落盘、有未读；广播发完全量即结束，不进入个人会话历史。

为什么检索不到？​

确认 conversationType=4 且 targetId=system；系统通知也要求服务已开通。

能撤回系统通知吗？​

可以用消息撤回接口按 messageId 撤回；撤回后客户端显示撤回占位。

审核拒绝的通知长什么样？​

系统通知内容为 message.blocked 语义，客户端按系统消息渲染。

相关链接​