泡泡 IM

外观

读取系统通知 ​

独立只读通知卡片流；仅操作当前鉴权账号。

GET /app/sdk/system-notifications

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

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

请求参数 ​

Query ​

参数类型必填说明
before_seqstring否严格小于该正十进制序号；首屏不传。
after_seqstring否严格大于该非负十进制序号，读取缓存缺失的新增记录。可与 before_seq 同时使用，要求 after_seq < before_seq。

请求示例 ​

bash
curl 'https://example.com/app/sdk/system-notifications' \
  -H "Authorization: Bearer $POPOIM_TOKEN"

使用说明 ​

  • 系统通知不属于好友/群会话，不注入 conversations；所有 id/seq 为十进制字符串，时间为 Unix 毫秒。
  • 每页最多 30 条，items 始终按 seq 降序。仅 before_seq 时向历史翻页；指定 after_seq 时，先取范围内下界之后最早的 30 条，再降序返回，使用 page.next_after_seq 继续补齐，保留原 before_seq 上界。上下界均不包含，每次查询还以返回的 inbox.last_seq 为上界。
  • 例如缓存缺少 31–90：after_seq=30、before_seq=91 首次返回 60–31，next_after_seq="60"；继续 after_seq=60、before_seq=91 返回 90–61，末页 has_more=false、两个下一页字段均为 null。
  • 按服务地址和账号隔离缓存，最多保留 120 条最近已获取通知；120 是缓存预算，不是接口接收上限，不主动下载全部历史。缓存连续覆盖当前 sync/WS 摘要时直接显示；有缺口才请求，不能仅凭最大 seq 判断完整。历史按需预加载，详情先读同账号缓存；缓存和预加载不自动标读。
  • 按 inbox.updated_at 合并 HTTP、sync 与 system_notifications.updated 的摘要，旧版本不回退已读或最新序号；其中同账号的完整通知仍可填补缓存缺口。事件 data={inbox,notification}，状态变化时 notification=null。
  • 列表成功展示后标读最大已展示 seq；推送详情成功显示后只标读该条 seq，不用 inbox.last_seq。浏览旧内容时新通知不改变滚动位置，也不标读尚未展示的新内容。

返回参数 ​

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

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

data 字段 ​

字段类型说明
inboxSystemNotificationInbox完整摘要。
itemsSystemNotification[]按 seq 降序，每页30条。
pageSystemNotificationPage分页边界。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "inbox": {
      "name": "系统通知",
      "visible": true,
      "last_seq": "12",
      "read_seq": "10",
      "unread_count": 2,
      "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": "查看详情"
        }
      }
    },
    "items": [
      {
        "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": "查看详情"
        }
      }
    ],
    "page": {
      "has_more": false,
      "next_before_seq": null,
      "next_after_seq": null
    }
  }
}

返回对象字段 ​

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

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

系统通知收件箱（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 时提供；业务参数对象。

通知分页（SystemNotificationPage） ​

字段类型说明
has_moreboolean当前查询范围内是否还有下一页；普通查询向旧翻页，增量查询向新翻页。
next_before_seqstring | null普通查询下一页 before_seq；末页或增量查询为 null。
next_after_seqstring | null增量查询下一页 after_seq，取本页最大序号；末页或普通查询为 null。

错误处理 ​

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

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

Copyright © 泡泡 IM