泡泡 IM

外观

修改系统通知状态 ​

标读、置顶、免打扰或移除入口。

POST /app/sdk/system-notifications/state

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数 ​

JSON Body ​

参数类型必填说明
actionstring是mark_read、set_pinned、set_muted、delete。
read_seqstring条件mark_read 必填。非负已读序号，单调推进并裁剪到服务器 last_seq。
valueboolean条件set_pinned / set_muted 必填。true 开启，false 关闭。

标有条件的必填项，只在相应操作或配置下需要提交。

请求示例 ​

bash
curl 'https://example.com/app/sdk/system-notifications/state' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"mark_read","read_seq":"12"}'

使用说明 ​

  • 系统通知不属于好友/群会话，不注入 conversations；所有 id/seq 为十进制字符串，时间为 Unix 毫秒。
  • 按 inbox.updated_at 合并 HTTP、sync 与 system_notifications.updated 的摘要，不用旧版本覆盖新状态；同账号的完整卡片仍可补缓存。事件 data={inbox,notification}，状态变化时 notification=null。
  • 列表成功展示后标读最大已展示 seq；推送详情成功显示后只标读该条 seq，不用 inbox.last_seq。浏览旧内容时新通知不改变滚动位置，也不标读尚未展示的新内容。
  • delete 隐藏入口、读到事务内最新序号并取消置顶，保留历史和免打扰；下一条新投递恢复入口。
  • inbox.unread_count 保留免打扰未读；unread.system 不计免打扰。桌面 badge=min(100,message+notice+system)。

返回参数 ​

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

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

data 字段 ​

字段类型说明
inboxSystemNotificationInbox修改后的摘要。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "inbox": {
      "name": "系统通知",
      "visible": true,
      "last_seq": "12",
      "read_seq": "12",
      "unread_count": 0,
      "pinned": false,
      "muted": false,
      "updated_at": 1792301400000,
      "last_notification_time": 1792301400000,
      "last_notification": {
        "id": "42",
        "seq": "12",
        "category": "report_result",
        "title": "举报处理结果",
        "summary": "你提交的举报已审核。",
        "body": "你提交的举报已审核。感谢你帮助维护社区秩序。",
        "fields": [
          {
            "label": "提交时间",
            "value": "2026-10-22 10:30"
          },
          {
            "label": "处理状态",
            "value": "已审核"
          }
        ],
        "created_at": 1792301400000,
        "action": {
          "type": "detail",
          "label": "查看详情"
        }
      }
    }
  }
}

返回对象字段 ​

数组中的每个对象使用同一套字段。点击名称跳到说明：

系统通知收件箱 · 系统通知卡片 · 通知标签值 · 通知跳转

系统通知收件箱（SystemNotificationInbox） ​

字段类型说明
namestring固定“系统通知”。
visibleboolean是否在消息列表显示独立入口。
last_seqstring最后投递序号；无内容为 "0"。
read_seqstring单调递增的已读边界；初始为 "0"。
unread_countinteger本收件箱未读，封顶 100；免打扰时仍保留。
pinnedboolean是否置顶。
mutedboolean是否免打扰。
updated_atinteger每用户严格递增的摘要版本，Unix 毫秒；初始为 0。
last_notification_timeinteger最后投递时间，Unix 毫秒；初始为 0。
last_notificationSystemNotification | null最后一条卡片；无投递时 null。

系统通知卡片（SystemNotification） ​

字段类型说明
idstring内容 ID，正十进制字符串；同内容可投递多人。
seqstring当前收件人内的连续序号，正十进制字符串。
categorystring例如 report_result；未知类别使用普通卡片。
titlestring标题。
summarystring摘要。
bodystring原生详情正文，按纯文本展示。
fieldsSystemNotificationField[]可选有序标签值列表，缺省 []。
created_atinteger向当前收件人投递的 Unix 毫秒时间。
actionSystemNotificationAction点击卡片的行为。

通知标签值（SystemNotificationField） ​

字段类型说明
labelstring标签。
valuestring纯文本值。

通知跳转（SystemNotificationAction） ​

字段类型说明
typestringdetail 原生详情、web HTTPS WebView、page 宿主注册页面；未知或无法执行时回退详情。
labelstring按钮文字。
urlstringweb 时提供；仅 HTTPS，无凭据，不拼接 IM Token。
pagestringpage 时提供；宿主注册路由标识，权限由目标后端验证。
paramsobjectpage 时提供；业务参数对象。

错误处理 ​

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

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

Copyright © 泡泡 IM