千问办公企业旗舰版开发者文档:会话 WebSocket。
认证方式见APP开发者文档 → 认证接入。
浏览器通过认证接入中的 createAppWebSocket 建立连接;服务端继续使用原有握手认证方式。连接后的消息协议不变。
建立双向会话连接,加入一个会话后接收历史重放、实时 ACP 事件和会话控制通知。单条连接同一时刻跟随一个会话;加入另一个会话会离开原会话。用户级跨会话通知使用独立的 notify-ws。
不要在 URL 中传 Token,也不要从浏览器构造可信身份 Header。HTTPS 页面使用 WSS。握手成功返回 101;认证、授权或服务不可用时握手失败,浏览器可能只暴露 error/1006,应通过现有 IAM 会话查询确认身份,不解析浏览器错误文字。
字段为 camelCase;不要直接把 HTTP APP 接口的 snake_case 请求体发送到 WS。未知通知和扩展字段应容错。
发送 control/join,params.sessionId 为已有会话 ID,params.lastSeqId 为客户端确认消费的位置;首次使用 0。不要将仅收到但尚未处理的数据记为已消费。
正常顺序为 replay_start → data 历史帧 → replay_end → 状态快照 → join_ack,然后跟随实时事件。join_ack 是 method 通知,不要只等待具有请求 id 的 result。
data.payload 保留 ACP JSON-RPC:session/update 携带 agent_message_chunk、agent_thought_chunk、tool_call、tool_call_update、plan、session_info_update 等;session/request_permission 表示需要用户交互。result.stopReason 表示回合结束,不表示整个会话终止。按事件 ID、序号及聚合覆盖范围合并重放;工具更新为局部更新,不清空未提供字段。完整业务字段见“订阅实时事件”页,但 WS 信封和 SSE 信封不同。
在 join_ack 接受后发送。控制请求使用唯一 id;ACK 表示受理,最终执行结果由后续事件和查询确认。
本页描述 APP 会话接入,不把实现中的其他运行时扩展视为已开放能力。HTTP + SSE 客户端继续使用文档中的 prompt、cancel、question-response 等 HTTP 操作;同一操作只选择一条发送路径。断线且未收到 ACK 时先查询服务端状态,不自动重发有副作用的操作。
收到 control/ping 时发送下列消息;客户端也可主动 ping 并等待 pong。客户端实现可采用 30 秒 ping、10 秒等待回复;服务端间隔由部署配置决定,不能假定固定值。
重放不等于严格恰好一次交付;客户端必须去重。退出登录、切换用户/组织、卸载应用时关闭旧连接并丢弃旧回调。不会因网络断开自动取消服务端任务。
以下使用同一个示例会话 ID;实际接入时替换为当前用户拥有的会话 ID。每个代码块是一条独立 WebSocket 文本消息,示例省略其他历史帧和状态快照,不表示完整消息序列。
客户端先发送上文的 join 请求。服务端完成历史重放和状态快照后,发送加入确认通知:
随后收到的文本增量示例:
客户端解码外层 type,再处理 payload 的 ACP 事件;成功合并该事件后才能保存已消费序号 13。currentSeqId 是服务端水位,不能直接当作客户端已经消费的位置。文本增量也不表示回合已经完成。
假设客户端已成功消费到序号 13,重新建立连接后发送:
服务端用以下两条控制通知标记重放边界,中间可能有 data 帧:
重放期间仍执行去重和聚合合并;重放结束后继续接收状态快照和 join_ack。若断线前的 new_prompt 是否受理不明确,先查询会话与消息状态,不随 join 自动重发输入。
- 接口:GET
/api/openapi/app/v1/sessions/chat-ws
用途
浏览器通过认证接入中的 createAppWebSocket 建立连接;服务端继续使用原有握手认证方式。连接后的消息协议不变。
建立双向会话连接,加入一个会话后接收历史重放、实时 ACP 事件和会话控制通知。单条连接同一时刻跟随一个会话;加入另一个会话会离开原会话。用户级跨会话通知使用独立的 notify-ws。
不要在 URL 中传 Token,也不要从浏览器构造可信身份 Header。HTTPS 页面使用 WSS。握手成功返回 101;认证、授权或服务不可用时握手失败,浏览器可能只暴露 error/1006,应通过现有 IAM 会话查询确认身份,不解析浏览器错误文字。
消息信封
| 字段 | 类型 | 说明 |
|---|---|---|
| type | string | control:控制层;data:ACP 会话事件 |
| payload | object | JSON-RPC 2.0 对象。请求带 id/method/params,响应带相同 id 和 result 或 error;通知通常无 id |
| seq | integer,可省略 | data 帧的事件序号(发送路径提供时)。不要求连续;不能与 SSE 的 id 或 HTTP 分页 next_cursor 混用 |
| payload.error | object | code、message、可选 data;控制失败与任务执行失败分开处理 |
加入、重放与实时订阅
发送 control/join,params.sessionId 为已有会话 ID,params.lastSeqId 为客户端确认消费的位置;首次使用 0。不要将仅收到但尚未处理的数据记为已消费。
| 控制消息 | 关键字段 / 行为 |
|---|---|
| replay_start、replay_end | 历史重放阶段边界,按 SDK 协议处理,不能把重放事件当成新消息重复追加 |
| join_ack | params.sessionId、currentSeqId、accepted;accepted 表示接入,不表示任务完成 |
| session_status | 会话状态变化;结合会话详情中的 current_turn、pending_action 刷新运行和待回答状态 |
| sandbox_status | 沙箱生命周期变化;刷新相关沙箱展示 |
| refresh_prompt_queue | 重新查询待执行消息队列 |
| content_blocked | 撤回被标记的内容;不能仅提示错误而继续展示被撤回正文 |
| ping、pong | 应用层心跳,使用 control 信封 |
发送操作
在 join_ack 接受后发送。控制请求使用唯一 id;ACK 表示受理,最终执行结果由后续事件和查询确认。
| method | params | 说明 |
|---|---|---|
| new_prompt | sessionId、text;可选 fileInfoList(每项 fileName、ossId) | 提交输入;ossId 是已存在文件路径,不是上传接口。new_prompt_ack 可含 promptId、turnId、accepted |
| cancel | sessionId | 请求取消当前执行;cancel_ack 不等于任务已停止 |
| question_response | sessionId、toolCallId、outcome、optionId、updatedInput | 回答待处理交互。updatedInput 含 questions 与 answers;questions 项含 question/header/options/multiSelect,answers 为问题到答案字符串的映射。使用 SDK 适配,不直接复制 HTTP question-response 的 answers 格式 |
| leave | sessionId | 离开当前订阅;返回 result.sessionId,不删除会话、不取消任务 |
心跳、错误和恢复
收到 control/ping 时发送下列消息;客户端也可主动 ping 并等待 pong。客户端实现可采用 30 秒 ping、10 秒等待回复;服务端间隔由部署配置决定,不能假定固定值。
| 关闭情况 | 客户端行为 |
|---|---|
| 1000 | 正常关闭;结合会话状态决定是否还需订阅 |
| 1001、异常断线/1006、1013 | 有上限的指数退避并加随机抖动;重连后重新 join、补历史 |
| 4001、1008 | 认证过期或访问策略拒绝;停止自动重试,交由 IAM 登录/权限处理 |
| 4002 | 会话不存在;停止订阅并刷新列表 |
| 4003、4008 | 容量限制或限流;退避,不快速循环重连 |
| 4009 | 历史代次失效;清理对应历史与游标,再重新加载 |