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.usOAuth 令牌响应中的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_typeaccount_credentialsaccount_idACCOUNT_ID2.3 重要区分REST 令牌与 SDK JWT这是最容易混淆的一点务必分清两套凭据体系体系用于签发方式凭据REST OAuth Token调用本文档的/v2/cobrowsesdk/*查询端点OAuth 2.0推荐 S2SClient ID / Client Secret / Account IDSDK JWT浏览器端session.start({ sdkToken })启动会话服务端用 SDK Secret 签 HS256 JWTSDK Key公开/ SDK Secret私密SDK JWT 的app_keyclaim 必须填SDK Key而非 API Keyrole_type取1客户或2Agentexp最小 30 分钟、最大 48 小时详见 cobrowse-sdk 的 JWT 认证文档。也就是说前端启动会话靠 JWT后端查询会话靠 OAuth Bearer Token两者不可混用。三、端点清单Cobrowse Sessions 域全部 4 个操作3.1 覆盖概览指标值端点操作Endpoint operations4路径模板Path templates4标签Tags13.2 Tag 索引Tag操作数Sessions43.3 端点明细按 Tag 分组Sessions方法端点摘要Operation IDGET/cobrowsesdk/live_sessions列出进行中的会话ListlivesessionsGET/cobrowsesdk/past_sessions列出历史会话ListpastsessionGET/cobrowsesdk/sessions/{sessionId}获取会话详情GetasessionGET/cobrowsesdk/sessions/{sessionId}/users列出会话内的用户Listsessionusers结构特征观察4 个操作全部为只读 GET无 POST/PUT/DELETE——说明该产品域的 REST 面聚焦于会话状态查询与审计而会话的创建、加入、结束均通过浏览器端 SDK 完成见下文第四节。路径设计呈现列表 → 详情 → 子资源的经典 REST 层级live_sessions/past_sessions是两张列表视图sessions/{sessionId}及其下的users是资源详情视图。四、会话模型理解查询对象的前提要正确使用上述查询端点必须先理解 Cobrowse 会话的数据模型。根据 cobrowse-sdk 技能文档每个会话包含两种角色角色role_type集成方式会话中的行为Customer客户1网站集成CDN 或 npm分享浏览器画面的一方Agent客服2Zoom 托管的 iframe 客服台或 BYOP 自定义 UI查看/协助客户的一方会话约束来自技能文档每会话最多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 名客户加 05 名 Agent通过该端点可以核对某会话当前有哪些人、各是什么角色。会话的典型生命周期客户先启动 → PIN 生成 → Agent 加入详见 get-started 指南 的Session Lifecycle部分。五、认证 scope 与粒度提示文档特别提醒scope 名称按操作定义且常使用细粒度 scope。这意味着不同端点可能需要不同的 scope例如列出进行中会话与查看会话详情未必共享同一个权限。在实现时先在官方 API Hub 对应操作页确认精确 scope文档明确要求Check the API Hub operation page在创建 OAuth App 时按需申请认证指南 的 Scope 章节给出user:read、meeting:read等常见 scope 与:admin管理级 scope 的选型建议只申请需要的随功能增长增量添加修改 scope 后需重新授权否则会出现invalid_scope或 401RUNBOOK 预检清单 第 2 步即要求核对 token 是否包含所需 scope。若令牌缺失权限常见表现为 401 Unauthorized 或错误码 2001TOKEN_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调用本文档端点时按以下决策树排查现象优先排查401 / invalid tokenOAuth 流程是否匹配、令牌是否过期、scope 是否缺失404 类行为端点路径/版本号是否写错、{sessionId}是否真实存在、ID 类型普通 ID vs UUID与编码是否正确429 限流是否缺少退避重试指数退避 jitter、是否高频轮询返回 HTML 而非 JSON令牌缺失或网关层问题正常应为 JSON 错误负载另外注意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/examplesWebhook 服务、录音流水线等跨端点编排范式。结语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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 1:39:33 · 阅读 1.2k 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.usOAuth 令牌响应中的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_typeaccount_credentialsaccount_idACCOUNT_ID2.3 重要区分REST 令牌与 SDK JWT这是最容易混淆的一点务必分清两套凭据体系体系用于签发方式凭据REST OAuth Token调用本文档的/v2/cobrowsesdk/*查询端点OAuth 2.0推荐 S2SClient ID / Client Secret / Account IDSDK JWT浏览器端session.start({ sdkToken })启动会话服务端用 SDK Secret 签 HS256 JWTSDK Key公开/ SDK Secret私密SDK JWT 的app_keyclaim 必须填SDK Key而非 API Keyrole_type取1客户或2Agentexp最小 30 分钟、最大 48 小时详见 cobrowse-sdk 的 JWT 认证文档。也就是说前端启动会话靠 JWT后端查询会话靠 OAuth Bearer Token两者不可混用。三、端点清单Cobrowse Sessions 域全部 4 个操作3.1 覆盖概览指标值端点操作Endpoint operations4路径模板Path templates4标签Tags13.2 Tag 索引Tag操作数Sessions43.3 端点明细按 Tag 分组Sessions方法端点摘要Operation IDGET/cobrowsesdk/live_sessions列出进行中的会话ListlivesessionsGET/cobrowsesdk/past_sessions列出历史会话ListpastsessionGET/cobrowsesdk/sessions/{sessionId}获取会话详情GetasessionGET/cobrowsesdk/sessions/{sessionId}/users列出会话内的用户Listsessionusers结构特征观察4 个操作全部为只读 GET无 POST/PUT/DELETE——说明该产品域的 REST 面聚焦于会话状态查询与审计而会话的创建、加入、结束均通过浏览器端 SDK 完成见下文第四节。路径设计呈现列表 → 详情 → 子资源的经典 REST 层级live_sessions/past_sessions是两张列表视图sessions/{sessionId}及其下的users是资源详情视图。四、会话模型理解查询对象的前提要正确使用上述查询端点必须先理解 Cobrowse 会话的数据模型。根据 cobrowse-sdk 技能文档每个会话包含两种角色角色role_type集成方式会话中的行为Customer客户1网站集成CDN 或 npm分享浏览器画面的一方Agent客服2Zoom 托管的 iframe 客服台或 BYOP 自定义 UI查看/协助客户的一方会话约束来自技能文档每会话最多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 名客户加 05 名 Agent通过该端点可以核对某会话当前有哪些人、各是什么角色。会话的典型生命周期客户先启动 → PIN 生成 → Agent 加入详见 get-started 指南 的Session Lifecycle部分。五、认证 scope 与粒度提示文档特别提醒scope 名称按操作定义且常使用细粒度 scope。这意味着不同端点可能需要不同的 scope例如列出进行中会话与查看会话详情未必共享同一个权限。在实现时先在官方 API Hub 对应操作页确认精确 scope文档明确要求Check the API Hub operation page在创建 OAuth App 时按需申请认证指南 的 Scope 章节给出user:read、meeting:read等常见 scope 与:admin管理级 scope 的选型建议只申请需要的随功能增长增量添加修改 scope 后需重新授权否则会出现invalid_scope或 401RUNBOOK 预检清单 第 2 步即要求核对 token 是否包含所需 scope。若令牌缺失权限常见表现为 401 Unauthorized 或错误码 2001TOKEN_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调用本文档端点时按以下决策树排查现象优先排查401 / invalid tokenOAuth 流程是否匹配、令牌是否过期、scope 是否缺失404 类行为端点路径/版本号是否写错、{sessionId}是否真实存在、ID 类型普通 ID vs UUID与编码是否正确429 限流是否缺少退避重试指数退避 jitter、是否高频轮询返回 HTML 而非 JSON令牌缺失或网关层问题正常应为 JSON 错误负载另外注意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/examplesWebhook 服务、录音流水线等跨端点编排范式。结语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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考