Zoom Cobrowse SDK REST API 端点全解：会话查询接口清单与协同浏览集成实战

Zoom Cobrowse SDK REST API 端点全解：会话查询接口清单与协同浏览集成实战

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

导读

本文档是 knowledge-work-plugins 仓库中partner-built/zoom-plugin/skills/rest-api/references/cobrowse-sdk-api.md的技术化深度解读。Cobrowse SDK（协同浏览）是 Zoom Video SDK 的一项能力，允许客服 Agent 与客户实时共享浏览器画面并协作。本文围绕其 REST API 的 4 个会话查询端点展开：先给出端点清单与调用基线，再结合仓库内 cobrowse-sdk 技能文档 的客户/Agent 双角色模型、JWT 认证与 PIN 会话机制，补充认证方式、分页、错误处理与实战调用示例，帮助你从"知道有哪些端点"进阶到"能正确查询会话状态并接入客服工作流"。

一、文档定位：一份"权威端点清单"而非编排指南

cobrowse-sdk-api.md是一份面向端点发现（endpoint discovery）的清单型文档。它在本仓库 rest-api 技能 的 39 个域参考文件中，与meetings.md、users.md、video-sdk-api.md等平级，专门覆盖 Cobrowse SDK 这一产品域的 REST 查询接口。

文档明确划定了使用边界，这是理解其价值的关键：

• 用途：端点方法与路径均源自官方 Zoom API Hub 的paths对象，用于端点发现与清单核对；
• 编排请查 examples：跨端点的调用编排模式应参考 rest-api/examples 目录，其中 meeting-lifecycle.md、recording-pipeline.md 展示了 REST API 与 Webhook 事件配合的典型做法，路径名称以本文档为准；
• scope 以 API Hub 页面为准：每个操作使用粒度较细的 scope 名称，实现前务必在 API Hub 操作页核对精确 scope。

从仓库结构看，该文档与 cobrowse-sdk 技能 分工明确：SDK 技能负责浏览器端 JS 集成（ZoomCobrowseSDK.init、session.start、pincode_updated事件等），而本文档负责服务端 REST 查询——两者共同构成完整的"浏览器端建会话 + 服务端查会话"闭环。

二、调用基线：Base URL 与认证

2.1 请求地址基线

所有 Cobrowse REST 端点以 Zoom REST API v2 为基址：

https://api.zoom.us/v2

完整的端点路径即https://api.zoom.us/v2后拼接下表路径。该基址与本仓库 rest-api 技能 中"Base URL"一节描述一致；如需数据驻留合规，可使用区域化域名（如api-eu.zoom.us、api-sg.zoom.us），OAuth 令牌响应中的api_url字段会指明用户所属区域。

2.2 认证方式

REST API 使用 OAuth 2.0 Bearer Token（服务端到服务端 Server-to-Server OAuth 为后端自动化推荐方式），请求头统一携带：

Authorization: Bearer <access_token> Content-Type: application/json

获取令牌的标准流程（详见 认证指南）：

curl -X POST "https://zoom.us/oauth/token" \ -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=account_credentials&account_id=ACCOUNT_ID"

2.3 重要区分：REST 令牌与 SDK JWT

这是最容易混淆的一点，务必分清两套凭据体系：

SDK JWT 的app_keyclaim 必须填SDK Key（而非 API Key），role_type取1（客户）或2（Agent），exp最小 30 分钟、最大 48 小时，详见 cobrowse-sdk 的 JWT 认证文档。也就是说：前端启动会话靠 JWT，后端查询会话靠 OAuth Bearer Token，两者不可混用。

三、端点清单：Cobrowse Sessions 域全部 4 个操作

3.1 覆盖概览

3.2 Tag 索引

3.3 端点明细（按 Tag 分组）

Sessions

结构特征观察：4 个操作全部为只读 GET，无 POST/PUT/DELETE——说明该产品域的 REST 面聚焦于会话状态查询与审计，而会话的创建、加入、结束均通过浏览器端 SDK 完成（见下文第四节）。路径设计呈现"列表 → 详情 → 子资源"的经典 REST 层级：live_sessions/past_sessions是两张列表视图，sessions/{sessionId}及其下的users是资源详情视图。

四、会话模型：理解查询对象的前提

要正确使用上述查询端点，必须先理解 Cobrowse 会话的数据模型。根据 cobrowse-sdk 技能文档，每个会话包含两种角色：

会话约束（来自技能文档）：

• 每会话最多1 名客户（超出报错1012 SESSION_CUSTOMER_COUNT_LIMIT）；
• 每会话最多5 名 Agent（超出报错1013 SESSION_AGENT_COUNT_LIMIT）；
• 每个浏览器最多1 个活动会话（报错1004 SESSION_COUNT_LIMIT）；
• 客户刷新页面后2 分钟内可自动重连（session_recoverable状态 →session.join()）。

这解释了/cobrowsesdk/sessions/{sessionId}/users端点的意义：一个会话内的用户集合理论上包含 1 名客户加 0～5 名 Agent，通过该端点可以核对"某会话当前有哪些人、各是什么角色"。会话的典型生命周期（客户先启动 → PIN 生成 → Agent 加入）详见 get-started 指南 的"Session Lifecycle"部分。

五、认证 scope 与粒度提示

文档特别提醒：scope 名称按操作定义且常使用细粒度 scope。这意味着不同端点可能需要不同的 scope，例如"列出进行中会话"与"查看会话详情"未必共享同一个权限。在实现时：

1. 先在官方 API Hub 对应操作页确认精确 scope（文档明确要求"Check the API Hub operation page"）；
2. 在创建 OAuth App 时按需申请（认证指南 的 Scope 章节给出user:read、meeting:read等常见 scope 与:admin管理级 scope 的选型建议：只申请需要的，随功能增长增量添加）；
3. 修改 scope 后需重新授权，否则会出现invalid_scope或 401（RUNBOOK 预检清单 第 2 步即要求核对 token 是否包含所需 scope）。

若令牌缺失权限，常见表现为 401 Unauthorized 或错误码 2001（TOKEN_INVALID 类），排查路径可参考 token-scope-playbook。

六、调用示例（基于清单的示意实现）

说明：以下 curl 示例依据端点路径模板与 Zoom REST API v2 的通用规范编写，用于演示调用形态；具体查询参数与响应字段以 API Hub 操作页的实际 OpenAPI 定义为准。

6.1 列出进行中的会话

curl -X GET "https://api.zoom.us/v2/cobrowsesdk/live_sessions" \ -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN" \ -H "Content-Type: application/json"

用于客服工作台的"当前在线会话"看板。从 rest-api 技能 的既有实践看，列表类接口通常支持page_size与next_page_token分页（详见 rate-limits 与 common-issues 中关于next_page_token优于旧式page_number的说明），高频轮询建议以 Webhook 事件替代（见 webhook-server 示例）。

6.2 列出历史会话

curl -X GET "https://api.zoom.us/v2/cobrowsesdk/past_sessions" \ -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

用于事后审计、客服质检或报表统计，通常配合时间范围查询参数使用。

6.3 获取单个会话详情

curl -X GET "https://api.zoom.us/v2/cobrowsesdk/sessions/{sessionId}" \ -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

{sessionId}为路径参数，来自"列出会话"响应中的会话标识。在编写业务代码时注意 ID 语义：Zoom REST API 存在普通 ID 与 UUID 之分，且以/开头或含//的 UUID 需要双重 URL 编码（encodeURIComponent(encodeURIComponent(uuid))），这是本仓库 api-architecture 明确强调的常见坑。

6.4 列出会话内用户

curl -X GET "https://api.zoom.us/v2/cobrowsesdk/sessions/{sessionId}/users" \ -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

配合会话详情可还原完整的会话参与者画像（客户 + 各 Agent 及其role_type、进出时间等），是质检、计费与合规审计的核心数据来源。

七、错误处理与调试速查

结合 rest-api 技能的预检 Runbook，调用本文档端点时按以下决策树排查：

另外注意，REST API 创建/管理的是 Zoom 平台资源，与 Meeting SDK / Video SDK 的浏览器端集成面相互独立（RUNBOOK 第 8 步），Cobrowse 会话的创建只能通过浏览器端 SDK 完成，REST 端点只负责查询。

八、从"端点清单"到"完整集成"的仓库导航

本文档只是 Cobrowse 集成拼图的一块。在 knowledge-work-plugins 仓库中，配套资料如下：

• 浏览器端 SDK 集成：cobrowse-sdk 技能（含客户/Agent 双角色、PIN 会话、注解工具、隐私掩码、远程协助、多标签持久化等全部特性）；
• 从零搭建：get-started.md（凭据获取 → JWT 签发 → 客户页集成 → Agent iframe 接入 → 联调测试）；
• 认证原理：JWT 认证 与 REST 认证指南；
• 典型客服场景：customer-support-cobrowsing 与 form-completion-assistant；
• 运行预检：cobrowse-sdk RUNBOOK 与 rest-api RUNBOOK；
• 编排模式：rest-api/examples（Webhook 服务、录音流水线等跨端点编排范式）。

结语

cobrowse-sdk-api.md虽短，却是服务端会话管理的"权威端点索引"：4 个 GET 操作覆盖了"实时会话列表 → 历史会话列表 → 会话详情 → 会话用户"的完整查询链路。在实际集成时，请以本文档为端点真相来源（canonical source），以 examples 为编排参考，配合 cobrowse-sdk 技能 的浏览器端实现，即可构建出"客户浏览器端发起会话 + 服务端实时监控会话状态"的完整协同浏览客服系统。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins