Skip to main content

用户通知 WebSocket

千问办公企业旗舰版开发者文档:用户通知 WebSocket。

认证方式见APP开发者文档 → 认证接入。
  • 接口:GET/api/openapi/app/v1/sessions/notify-ws

用途

浏览器通过认证接入中的 createAppWebSocket 建立连接;服务端继续使用原有握手认证方式。连接后的消息协议不变。 接收当前用户的跨会话通知;不需要 session_id,也不需要 join。每个已完成接入的应用维护一条连接,页面内业务共享订阅。它不承载聊天回复正文;聊天实时事件使用 chat-ws 或单会话 events/stream。 不要在 URL 中传 Token、用户 ID 或组织 ID,也不要构造可信身份头。握手成功为 101;认证、权限或服务不可用会导致握手失败,浏览器可能只暴露 error/1006,应由 IAM 会话查询区分原因。

消息格式

使用裸 JSON-RPC 2.0,不包含 chat-ws 的 type/payload 外层信封。业务通知通常不带 id,不要求客户端逐条 ACK;ping/pong 是心跳,不是业务处理确认。
{"jsonrpc":"2.0","method":"new_message","params":{"sessionId":"session-1","hasNew":true,"unreadCount":2,"ts":1792800000000}}

服务端消息

methodparams 字段客户端处理
initunreadSessions 数组;每项 sessionId、unreadCount,可选 lastMessageAt替换未读快照。每次连接都可能收到;同时刷新列表和当前会话,补偿离线期间错过的变更
new_messagesessionId、hasNew、unreadCount,可选 ts更新该会话未读;hasNew=false 或 unreadCount=0 可表示已读。不是聊天正文,不应追加到消息列表
session_namesessionId、name,可选 ts刷新会话名称与列表。若直接合并 name,需防止较旧 ts 覆盖较新名称
session_feed_changed可选 reason、sessionId、schedulerTaskId刷新最近/置顶及相关任务列表;未知 reason 仍按刷新提示处理
sandbox_statussessionId;状态字段可能为 status、sandboxStatus 或 sandbox_status;可选 sandboxId、ts、detail刷新沙箱及相关会话。常见状态 running、paused、killed、stopped;容忍未知值
im_connection_status_changed可选连接/渠道/运行状态提示字段如消费 IM 渠道功能,重新查询连接状态;提示不是权威状态
ping无业务参数回复裸 pong
pong无业务参数清除客户端心跳超时计时
sessionId 等字段为 camelCase。ts/lastMessageAt 为时间提示,不是恢复游标。未知 method 或扩展字段应忽略或容错,不应使整个连接失效。

心跳与重连

{"jsonrpc":"2.0","method":"ping"}
{"jsonrpc":"2.0","method":"pong"}
服务端和客户端均可主动 ping。客户端可每 30 秒发送 ping,等待 pong 或服务端 ping 最多 10 秒,超时关闭连接后重连;服务端心跳由部署配置控制。重连采用有上限的指数退避和随机抖动,例如 1 秒起步、上限 30 秒。网络恢复或页面恢复可见时可触发重试。 4001(身份过期)或 1008(访问策略拒绝)时停止自动重试,按认证接入与资源权限要求处理;1001、1006、1013 等断线按退避恢复。握手失败不一定携带这些业务关闭码。切换账号/组织、退出登录或页面卸载必须关闭旧连接、取消计时器并忽略迟到回调。

交付语义与页面更新

通知通过 Redis Pub/Sub 分发,没有离线消息积压,也没有 lastSeqId、Last-Event-ID 或补发保证。通知可能重复、乱序或丢失,不能作为账务、任务完成或业务事务的唯一证据。init 的未读快照不能补回所有名称和列表变更。 收到通知后合并短时间内的刷新请求,再读取 HTTP 权威状态;重连后主动刷新。保留低频轮询或页面聚焦刷新兜底。未读状态以服务端快照和通知为准,不能仅因打开一个页面就声称服务端已标记已读。 APP2 使用 HTTP + 单会话 SSE 处理聊天,同时独立接入本通知连接更新跨会话列表、未读和相关状态;无需为此改用 chat-ws。

浏览器接收示例

以下只演示握手与协议解码;生产客户端还需实现上述重连、超时与身份清理。onNotification 由应用提供,负责验证参数并刷新业务数据。
async function subscribeNotifications(onNotification) {
  const socket = await createAppWebSocket('/api/openapi/app/v1/sessions/notify-ws');
  socket.onmessage = ({ data }) => {
    let message;
    try { message = JSON.parse(data); } catch { return; }
    if (!message || typeof message.method !== 'string') return;
    if (message.method === 'ping') {
      socket.send(JSON.stringify({ jsonrpc: '2.0', method: 'pong' }));
    } else if (message.method !== 'pong') {
      onNotification(message.method, message.params);
    }
  };
  return () => socket.close(1000);
}

跨会话通知示例

以下每个代码块是一条服务端推送的独立 WebSocket 文本消息,均为裸 JSON-RPC,不添加 type/payload 外层。

连接后的未读快照

{"jsonrpc":"2.0","method":"init","params":{"unreadSessions":[{"sessionId":"session-1","unreadCount":2}]}}
用 unreadSessions 替换本地未读快照,同时重新查询会话列表;空数组表示当前快照没有未读会话,不代表会话列表为空。

新消息与会话改名

{"jsonrpc":"2.0","method":"new_message","params":{"sessionId":"session-1","hasNew":true,"unreadCount":3,"ts":1792800000000}}
更新 session-1 的未读提示并刷新相关状态。即使用户正在查看另一个会话,也能收到这条通知;它不包含聊天正文,不表示当前回合已经完成。
{"jsonrpc":"2.0","method":"session_name","params":{"sessionId":"session-1","name":"数据分析","ts":1792800001000}}
合并触发一次会话列表刷新,通过 HTTP 查询取得最新名称,避免乱序通知覆盖新状态。

已读变化

{"jsonrpc":"2.0","method":"new_message","params":{"sessionId":"session-1","hasNew":false,"unreadCount":0,"ts":1792800002000}}
清除对应会话的未读提示。这是服务端状态变化通知,不是客户端发送的“标记已读”请求;不要把上述消息反向发送来修改服务端状态。