千问办公企业旗舰版开发者文档:用户通知 WebSocket。
认证方式见APP开发者文档 → 认证接入。
浏览器通过认证接入中的 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 是心跳,不是业务处理确认。
sessionId 等字段为 camelCase。ts/lastMessageAt 为时间提示,不是恢复游标。未知 method 或扩展字段应忽略或容错,不应使整个连接失效。
服务端和客户端均可主动 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 由应用提供,负责验证参数并刷新业务数据。
以下每个代码块是一条服务端推送的独立 WebSocket 文本消息,均为裸 JSON-RPC,不添加 type/payload 外层。
用 unreadSessions 替换本地未读快照,同时重新查询会话列表;空数组表示当前快照没有未读会话,不代表会话列表为空。
更新 session-1 的未读提示并刷新相关状态。即使用户正在查看另一个会话,也能收到这条通知;它不包含聊天正文,不表示当前回合已经完成。
合并触发一次会话列表刷新,通过 HTTP 查询取得最新名称,避免乱序通知覆盖新状态。
清除对应会话的未读提示。这是服务端状态变化通知,不是客户端发送的“标记已读”请求;不要把上述消息反向发送来修改服务端状态。
- 接口: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 是心跳,不是业务处理确认。
服务端消息
| method | params 字段 | 客户端处理 |
|---|---|---|
| init | unreadSessions 数组;每项 sessionId、unreadCount,可选 lastMessageAt | 替换未读快照。每次连接都可能收到;同时刷新列表和当前会话,补偿离线期间错过的变更 |
| new_message | sessionId、hasNew、unreadCount,可选 ts | 更新该会话未读;hasNew=false 或 unreadCount=0 可表示已读。不是聊天正文,不应追加到消息列表 |
| session_name | sessionId、name,可选 ts | 刷新会话名称与列表。若直接合并 name,需防止较旧 ts 覆盖较新名称 |
| session_feed_changed | 可选 reason、sessionId、schedulerTaskId | 刷新最近/置顶及相关任务列表;未知 reason 仍按刷新提示处理 |
| sandbox_status | sessionId;状态字段可能为 status、sandboxStatus 或 sandbox_status;可选 sandboxId、ts、detail | 刷新沙箱及相关会话。常见状态 running、paused、killed、stopped;容忍未知值 |
| im_connection_status_changed | 可选连接/渠道/运行状态提示字段 | 如消费 IM 渠道功能,重新查询连接状态;提示不是权威状态 |
| ping | 无业务参数 | 回复裸 pong |
| pong | 无业务参数 | 清除客户端心跳超时计时 |