发布系统通知

只供可信宿主后端发布；普通 IM Token 没有发布权限。

POST /app/sdk/system-notifications/publish

调用方： 宿主后端　·　认证： SDK 后端密钥

请求头：Authorization: Bearer <sdkSecret>。只允许宿主后端调用，密钥不能放到客户端。密钥来源与认证流程见认证与登录，PHP / Java / Go / JavaScript / C# 实现见后端认证示例。

请求参数

JSON Body

参数	类型	必填	说明
source	string	是	最多64位 ASCII 字母、数字、点、下划线、冒号或连字符。
event_key	string	是	来源内稳定业务事件键，最多128位同类标识。
user_ids	string[]	是	每批1至1000个有效外部用户ID；重复收件人不重复投递。
category	string	是	最多64位业务类别标识。
title	string	是	最多100字。
summary	string	否	最多300字；省略时由正文生成。
body	string	是	纯文本，最多10000字且20000 UTF-8字节。
fields	object[]	否	有序 {label,value} 列表，最多20项；label最多80字、value最多500字，JSON不超过4096字节。
action	object	否	默认原生详情；web额外提供url，page提供page和params对象。

请求示例

curl 'https://example.com/app/sdk/system-notifications/publish' \
  -H "Authorization: Bearer $POPOIM_SDK_SECRET" \
  -H 'Content-Type: application/json' \
  --data '{"source":"host","event_key":"announcement:20261022","user_ids":["chenyue"],"category":"announcement","title":"服务公告","summary":"服务已恢复正常。","body":"服务已恢复正常。感谢你的耐心等待。","fields":[],"action":{"type":"detail","label":"查看详情"}}'

使用说明

• 同 source/event_key 内容不可变，可分批投递更多用户。投递唯一键包含收件人，通知、seq和摘要同事务提交。
• web仅接受无凭据HTTPS URL（最多2048字节）；page仅打开宿主已注册路由（最多128位），params为对象且JSON最多4096字节。label最多40字，整张内容JSON最多28000字节。客户端不复制发布端硬限制。
• 举报首次审核/关闭后给举报人发送固定公开结果及提交时间，内部备注、证据、管理员身份不公开；不可投递账号不阻止管理员处理。
• 推送复用现有provider，自定义数据为 {type:"system_notification",notification_id,recipient_user_id}，recipient_user_id为外部用户ID。宿主点击时核对账号，不匹配回主页；未知类型安全回主页。
• 新装使用 popoim_install.sql；已完成的一次性迁移入口已移除。存量升级先备份并增量调整表结构，不向旧库导入全新安装 SQL，见版本更新。实时与推送为尽力通知，重连后以数据库同步为准。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
code	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msg	string	成功通常为 ok，失败时为错误说明。
data	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
id	string	共享内容ID。
delivered	integer	本次新增投递数；重试为0。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "42",
    "delivered": 1
  }
}

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回首页与会话接口列表 · HTTP 请求约定