Zoom 分组会议室Breakout Rooms跨平台编程指南基于 knowledge-work-plugins Meeting 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本篇技术指南基于 knowledge-work-plugins 仓库中 Zoom 插件的 Meeting SDK 技能参考文档 breakout-rooms.md系统讲解如何通过 SDK 与 REST API 以编程方式创建、分配、开启、关闭并管理 Zoom 会议的分组会议室Breakout Rooms。读完本文你将掌握 Web、iOS、Android、Windows、macOS 五个平台的 Breakout Room API 用法、REST API 预分配房间的请求格式、角色权限模型、容量限制与录制限制以及 Video SDK 平台下的 Subsessions 替代方案能够直接在自己的集成项目中实现分组讨论的全流程自动化控制。1. 什么是 Breakout Rooms各平台支持程度如何Breakout Rooms分组会议室允许主持人将会议参与者拆分到更小的分组中实现分组讨论、培训演练、头脑风暴等场景。本文的核心骨架文档覆盖了各平台 SDK 中创建、管理和控制 breakout rooms 的完整 API。该文档给出了如下平台支持矩阵这是选型前的第一张对照表平台支持程度说明Web SDK完整支持完整 APIiOS SDK完整支持Creator Admin 辅助接口helpersAndroid SDK完整支持Creator Admin 辅助接口helpersWindows SDK完整支持Controller 接口macOS SDK完整支持Controller 接口Linux SDK有限支持仅基础功能Video SDK不同实现使用 Subsessions 概念并非原生 breakout rooms重要提示Video SDK 没有原生 breakout rooms。它采用的是 Subsessions子会话概念需要自行进行手动会话管理详见第 9 节。从仓库结构看meeting-sdk 技能入口将该文档定位为 Features 参考之一Programmatic breakout room management与 授权签名、Webinar 功能、故障排查 等参考并列说明 breakout rooms 是 Meeting SDK 集成中独立而高频的功能模块。2. REST API创建预分配Pre-assigned分组房间在会议开始前可以通过 REST API 创建带有预分配 breakout rooms 的会议从而在会议启动时参与者已经按名单归组。请求端点POST /v2/users/{userId}/meetings请求体示例{ topic: Team Workshop, type: 2, settings: { breakout_room: { enable: true, rooms: [ { name: Team Alpha, participants: [user1example.com, user2example.com] }, { name: Team Beta, participants: [user3example.com, user4example.com] } ] } } }关键字段说明type: 2表示会议类型为会议meetingsettings.breakout_room.enable: true开启 breakout rooms 功能rooms数组中每个元素是一个分组包含name房间名和participants按邮箱预分配的参与者列表。关键限制预分配的房间不会自动开启。会议开始后主持人必须手动开启 breakout rooms且不存在任何 REST API 可以自动开启房间。这一限制直接影响架构设计如果你的集成目标是会议一开始就自动进入分组讨论则必须在会议内通过 SDK见下文各平台实现触发开启动作或由主持人/机器人留在会内完成开启。3. Web SDK完整的 Breakout Room APIWeb SDKClient View即 CDN 提供的ZoomMtg全局对象回调式 API提供了 breakout rooms 最完整的 API 面。以下为原文档覆盖的全部接口。3.1 创建分组房间// 创建 5 个房间名称自动生成Room 1, Room 2, ... ZoomMtg.BreakoutRoom.createBreakoutRoom({ data: 5, success: (response) console.log(Rooms created:, response), error: (error) console.error(Error:, error) }); // 创建带自定义名称的房间 ZoomMtg.BreakoutRoom.createBreakoutRoom({ data: [ { name: Engineering }, { name: Design }, { name: Product } ], success: (response) console.log(Rooms created:, response), error: (error) console.error(Error:, error) });data参数支持两种形态传一个数字表示按数量创建名称自动生成为 Room N传一个对象数组则为每个房间指定name。3.2 查询分组房间列表ZoomMtg.BreakoutRoom.getBreakoutRooms({ success: (response) { const rooms response.result.rooms; rooms.forEach(room { console.log(Room ID: ${room.boId}, Name: ${room.name}); }); }, error: (error) console.error(Error:, error) });响应中每个房间的核心标识是boIdbreakout room ID与name。boId是后续分配、移动用户时必须使用的房间标识。3.3 分配参与者到房间// 先获取未分配参会者列表 ZoomMtg.BreakoutRoom.getUnassignedAttendeeList({ success: (response) { const unassigned response.result.unassignedAttendeeList; console.log(Unassigned:, unassigned); } }); // 将某用户分配到指定房间 ZoomMtg.BreakoutRoom.assignUserToBreakoutRoom({ targetRoomId: room-id-here, userId: 12345678, success: (response) console.log(Assigned:, response), error: (error) console.error(Error:, error) });3.4 在房间之间移动参与者ZoomMtg.BreakoutRoom.moveUserToBreakoutRoom({ targetRoomId: destination-room-id, userId: 12345678, success: (response) console.log(Moved:, response), error: (error) console.error(Error:, error) });3.5 开启分组房间这是最复杂的调用options对象控制房间开启后的行为ZoomMtg.BreakoutRoom.openBreakoutRooms({ options: { isAutoJoinRoom: false, // 让参与者自己选择房间 isBackToMainSessionEnabled: true, // 允许随时返回主会场 isTimerEnabled: true, // 启用倒计时 timerDuration: 1800, // 30 分钟秒 needCountDown: true, // 显示倒计时 waitSeconds: 60 // 自动加入前的等待秒数 }, success: (response) console.log(Rooms opened:, response), error: (error) console.error(Error:, error) });参数语义对照结合 Windows 示例中SetBOOption的等价字段可以确认这些开关在各平台的语义一致参数语义对应 Windows SDK 字段isAutoJoinRoom是否自动将已分配用户拉入房间IsAutoMoveAllAssignedParticipantsEnabledisBackToMainSessionEnabled参与者能否随时返回主会场IsParticipantCanReturnToMainSessionAtAnyTimeisTimerEnabled/timerDuration分组计时器及分钟/秒数IsBOTimerEnabled/timerDurationneedCountDown/waitSeconds关闭前倒计时提醒IsTimerAutoStopBOEnabled/countdown3.6 关闭分组房间ZoomMtg.BreakoutRoom.closeBreakoutRooms({ success: (response) console.log(Rooms closed:, response), error: (error) console.error(Error:, error) });3.7 向所有房间广播消息ZoomMtg.BreakoutRoom.broadcast({ message: Please return to the main room in 2 minutes, success: (response) console.log(Broadcast sent:, response), error: (error) console.error(Error:, error) });3.8 查询用户状态// 获取当前用户的 breakout room ZoomMtg.BreakoutRoom.getCurrentBreakoutRoom({ success: (response) { const { roomId, name, attendeeStatus } response.result; console.log(Current room: ${name}, Status: ${attendeeStatus}); } }); // attendeeStatus 取值 // 1: UNASSIGNED - 未分配到任何房间 // 2: ASSIGNED_NOT_JOIN - 已分配但尚未加入 // 3: IN_BO - 当前在 breakout room 中attendeeStatus的三态模型是编写自动化分配逻辑的关键状态 3 的用户应使用移动而非分配否则会触发冲突。3.9 Web 端实操注意事项仓库中专门有一篇 Component View Breakout Rooms 参考它补充了原文档未展开的上下文约束Breakout rooms 是主持人控制的功能。即使 SDK UI 支持 breakout rooms编程方式的创建/开启/关闭通常同时要求正确的角色host/co-host、会议本身已启用 breakout rooms、以及你所用视图类型Client View 的ZoomMtg或 Component View 的ZoomMtgEmbedded确实提供对应 API两种视图的 API不保证对等dont assume parity自动化前需要确认具体 SDK 版本和视图类型下 API 是否存在。另外从 SKILL.md 的 Web 快速入门可以确认CDN 分发提供的是ZoomMtgClient View回调风格npm 包zoom/meetingsdk提供的是ZoomMtgEmbeddedComponent ViewPromise 风格。上文所有ZoomMtg.BreakoutRoom.*示例均属于 Client View API。4. iOS SDKCreator/Admin 双 Helper 模型iOS 端通过 MobileRTC 框架的 Meeting Service 获取 breakout room 辅助接口。4.1 获取 Helpers#import MobileRTC/MobileRTC.h // 获取会议服务 MobileRTCMeetingService *meetingService [[MobileRTC sharedRTC] getMeetingService]; // 获取 breakout room creator用于创建房间 MobileRTCBOCreator *boCreator [meetingService getCreatorHelper]; // 获取 breakout room admin用于管理房间 MobileRTCBOAdmin *boAdmin [meetingService getAdminHelper];4.2 创建房间// 创建 3 个 breakout rooms [boCreator createBreakoutRoom:3 completion:^(NSError *error) { if (error) { NSLog(Error: %, error.localizedDescription); } else { NSLog(Rooms created); } }]; // 创建指定名称的房间 [boCreator createBreakoutRoomWithName:Engineering completion:^(NSError *error) { // 处理结果 }];4.3 管理房间// 开启所有房间 [boAdmin openAllRoomsCompletion:^(NSError *error) { if (!error) { NSLog(Rooms opened); } }]; // 将用户分配到房间 [boAdmin assignUser:userId toRoom:roomId completion:^(NSError *error) { if (!error) { NSLog(User assigned); } }]; // 关闭所有房间 [boAdmin closeAllRoomsCompletion:^(NSError *error) { if (!error) { NSLog(Rooms closed); } }];4.4 事件处理房间状态变更iOS 端通过MobileRTCMeetingServiceDelegate协议回调接收 breakout room 状态变化interface MyDelegate : NSObject MobileRTCMeetingServiceDelegate end implementation MyDelegate - (void)onMeetingBreakoutRoomStatusChanged:(MobileRTCBreakoutRoomStatus)status { switch (status) { case MobileRTCBreakoutRoomStatusNotStarted: NSLog(Breakout rooms not started); break; case MobileRTCBreakoutRoomStatusStarted: NSLog(Breakout rooms started); break; case MobileRTCBreakoutRoomStatusClosed: NSLog(Breakout rooms closed); break; } } end三态状态枚举NotStarted / Started / Closed与 Web 端房间生命周期一致跨平台的状态机逻辑可以复用。5. Android SDKIn-Meeting Controller 模型Android 端的 API 组织方式为ZoomSDK单例 →meetingService→inMeetingBreakoutRoomController再向下取 creator/admin helper。5.1 获取 Helpersimport us.zoom.sdk.ZoomSDK val zoomSDK ZoomSDK.getInstance() val meetingService zoomSDK.meetingService val boController meetingService?.inMeetingBreakoutRoomController // 获取 creator用于创建房间 val creator boController?.getCreatorHelper() // 获取 admin用于管理房间 val admin boController?.getAdminHelper()5.2 创建房间// 创建 breakout rooms val error creator?.createBreakoutRoom(5) // 创建 5 个房间 if (error SDKError.SDKERR_SUCCESS) { Log.d(Breakout, Rooms created) } // 创建指定名称的房间 creator?.createBreakoutRoomWithName(Engineering)注意 Android 的错误处理风格与 iOS 不同不是 completion 回调而是同步返回SDKError枚举SDKError.SDKERR_SUCCESS表示成功与仓库 troubleshooting 参考 中错误码 0 通常表示成功的说明一致。5.3 管理房间// 开启所有房间 admin?.openAllRooms() // 将用户分配到房间 admin?.assignUser(userId, roomId) // 在房间之间移动用户 admin?.assignUser(userId, newRoomId) // 自动从原房间移除 // 广播消息 admin?.broadcastToAll(Please return in 2 minutes) // 关闭所有房间 admin?.closeAllRooms()一个值得注意的实现细节Android 上移动用户复用assignUser接口向新房间再次 assign 即自动从旧房间移除与 Web 端独立的moveUserToBreakoutRoom形成对照——跨平台移植代码时不能直接按方法名对译。6. Windows / macOS 桌面 SDKController 与事件回调6.1 WindowsC#include meeting_breakout_rooms_interface.h class MyBreakoutRoomsEvent : public IMeetingBreakoutRoomsEvent { public: void OnBreakoutRoomsStartedNotification(const wchar_t* stBID) override { // 处理 breakout rooms 开启事件 wprintf(LBreakout rooms started: %s\n, stBID); } }; // 获取 controller IMeetingBreakoutRoomsController* pController pMeetingService-GetBreakoutRoomsController(nullptr); // 注册事件处理器 pController-SetEvent(new MyBreakoutRoomsEvent()); // 获取房间列表 IListIBreakoutRoomsInfo** pRoomList pController-GetBreakoutRoomsInfoList(); for (int i 0; i pRoomList-GetItemCount(); i) { IBreakoutRoomsInfo* pRoom pRoomList-GetItem(i); wprintf(LRoom: %s (ID: %s)\n, pRoom-GetBreakoutRoomName(), pRoom-GetBID()); } // 加入 breakout room pController-JoinBreakoutRoom(Lroom-id); // 离开 breakout room pController-LeaveBreakoutRoom();6.2 macOSObjective-C#import ZoomSDK/ZoomSDK.h // 获取 controller ZoomSDKBreakoutRoomsController *boController [[ZoomSDK sharedSDK] getMeetingService] getBreakoutRoomsController]; // 加入 breakout room [boController requestJoinBreakoutRoom:room-id]; // 离开 breakout room [boController requestLeaveBreakoutRoom]; // 关闭所有房间仅 host 可用 [boController requestCloseAllBreakoutRooms];6.3 仓库纵深补充Windows 端的五角色模型原文档的 Windows 示例展示了GetBreakoutRoomsController这一简化 Controller 接口。仓库中更完整的 Windows Breakout Rooms 示例基于 Windows Meeting SDK v6.7.2.26830揭示了底层实际的五角色接口模型——同一个用户在会内可以同时持有多个角色角色接口能力DataIBOData读取 breakout room 信息、用户分配、名称AdminIBOAdmin管理运行中的 BO、接收求助请求、分配用户、广播CreatorIBOCreator创建/修改 BO、配置选项、预分配用户AssistantIBOAssistant无需分配即可加入任意 BO次要角色AttendeeIBOAttendee加入被分配的 BO、向 admin 发起求助典型角色组合Host持有 Creator Admin DataCo-host持有 Admin Data普通参会者持有 Attendee Data。该示例还给出了原文档未覆盖的两块重要细节其一SetBOOption的完整选项集对应 Web 端openBreakoutRooms的options参数的桌面等价物BOOption option; option.IsBOTimerEnabled true; option.timerDuration 15; // 15 分钟 option.IsTimerAutoStopBOEnabled true; // 计时结束后自动关闭 option.countdown BOStopCountdown_Seconds_60; // 60 秒关闭预警 option.IsParticipantCanChooseBO true; // 参与者可自选房间 option.IsParticipantCanReturnToMainSessionAtAnyTime true; option.IsAutoMoveAllAssignedParticipantsEnabled true; option.IsUserConfigMaxRoomUserLimitsEnabled true; option.nUserConfigMaxRoomUserLimits 10; // 每房间人数上限 bool success creator-SetBOOption(option);其二BO Controller 错误码表可作为桌面端错误处理的依据码名称含义0BOControllerError_NULL_POINTERBO controller 为空——SDK 未初始化1BOControllerError_WRONG_CURRENT_STATUS当前状态不正确2BOControllerError_TOKEN_NOT_READYToken 未就绪3BOControllerError_NO_PRIVILEGE无权限执行该操作4BOControllerError_BO_LIST_IS_UPLOADINGBO 列表正在上传5BOControllerError_UPLOAD_FAILBO 列表上传失败6BOControllerError_NO_ONE_HAS_BEEN_ASSIGNED无法开启——没有用户被分配100BOControllerError_UNKNOWN未知错误该示例中给出的端到端工作流为注册角色监听器 → 收到 Creator 角色后配置选项并创建房间 → 收到创建回调后通过IBOData查找用户/房间 ID 并预分配 → Admin 调用StartBO()开启 → 参会者端收到 Attendee 角色后JoinBo()。这一角色驱动、回调串联的模型是桌面端实现自动化 breakout 流程的标准结构。7. 权限模型Host / Co-Host / Participant原文档给出了跨平台一致的权限矩阵操作HostCo-HostParticipant创建 breakout rooms允许允许禁止开启 breakout rooms允许允许禁止关闭 breakout rooms允许允许禁止分配参与者允许允许禁止移动参与者允许禁止禁止广播消息允许允许禁止加入任意房间允许允许*禁止*Co-host 只能加入由 host 分配的房间。权限模型与第 6.3 节的五角色接口一一对应Web/iOS/Android 的 helpercreator/admin与桌面端的IBOCreator/IBOAdmin就是权限在 API 层的投影——没有对应角色时helper 为空或调用返回无权限错误如BOControllerError_NO_PRIVILEGE。设计集成方案时应以应用运行时实际获得的角色为准而非登录身份。8. 容量限制与工程陷阱8.1 容量上限账户类型最大房间数最大参与人数Standard50 个房间共 500 人Large Meeting Add-on100 个房间共 1,000 人8.2 录制限制云录制只录制主会场本地录制只录制录制者所在的房间Host 无法录制自己不在的 breakout room。这三条决定了分组讨论全程留痕类需求必须改变方案要么 host/机器人巡回进入各房间做本地录制要么只接受主会场云录制。8.3 无法自动开启预分配房间原文档将此列为Critical限制不存在任何 API 可以自动开启预分配的 breakout rooms会议开始后必须由 host 手动开启。这与第 2 节的 REST 限制呼应意味着REST 预分配 SDK 自动开启是最可行的半自动架构纯 REST 路径无法闭环。8.4 主会场会话超时Breakout rooms 进行期间如果主会场没有任何参与者留下主会场可能在超时后关闭。必须确保至少一名参与者host 或机器人留在主会场。对无人值守的自动化会议例如 bot 主持的培训会议这一点是常见的隐性故障源——主会场一旦关闭所有房间的closeBreakoutRooms流程都会失效。9. 最佳实践原文档三条 仓库补充9.1 创建前先探测支持能力ZoomMtg.BreakoutRoom.getBreakoutRoomOptions({ success: (response) { if (response.result.isSupportBreakoutRoom) { // 会议支持 breakout rooms继续创建 } } });isSupportBreakoutRoom是防御性编程的第一道闸门不同会议类型普通会议/ Webinar、不同账户配置下 breakout rooms 可能整体不可用直接创建会失败。9.2 分配前检查用户状态// 分配前先检查 ZoomMtg.BreakoutRoom.getUserStatus({ userId: userId, success: (response) { const { attendeeStatus } response.result; if (attendeeStatus 3) { // IN_BO // 用户已在某个房间中——应使用移动而不是分配 } } });9.3 错误分类处理function handleBreakoutError(error) { switch (error.method) { case createBreakoutRoom: if (error.errorMessage.includes(not support)) { alert(Breakout rooms not enabled for this meeting); } break; case assignUserToBreakoutRoom: if (error.errorMessage.includes(not host)) { alert(Only host/co-host can assign participants); } break; } }按error.method定位失败操作、按errorMessage关键字区分功能未开启与权限不足这两类错误的处理路径完全不同前者需要改会议设置或降级 UI后者需要提示角色问题。9.4 仓库补充Web 端视图与角色的双重确认结合 component-view-breakout-rooms 参考 的排查模式Web 端遇到breakout rooms API 无效/缺失时推荐按序确认三件事当前运行身份是 host 还是 participant使用的是 Client ViewZoomMtg还是 Component ViewZoomMtgEmbedded且该视图是否提供所需 API会议设置中 breakout rooms 是否已启用getBreakoutRoomOptions探测。这三步与 9.1 的isSupportBreakoutRoom探测、第 7 节权限矩阵共同构成 Web 端 breakout 问题的完整诊断链。10. Video SDK 平台Subsessions 替代路线Video SDK没有原生 breakout rooms。官方替代概念是 Subsessions需要自行实现分组逻辑创建多个独立的 Video SDK 会话subsessions以编程方式在会话之间移动参与者自行实现房间管理逻辑计时、广播、返回主会场等。仓库的 Video SDK Web 技能文档 在功能清单中将 Subsessions 标注为 Breakout room support并从 API 映射表可见其入口为client.getSubsessionClient()。可以推断在 Video SDK 场景下breakout room 完全退化为应用层的多会话编排问题本文第 3 至 6 节的 Meeting SDK API 均不适用如果产品形态要求自绘 UIVideo SDK 的典型场景分组讨论的实现成本与 Meeting SDK 路径不在同一量级选型时应将这一点计入决策。11. 小结按平台选择实现路径将原文档骨架与仓库补充材料合并后各平台的推荐实现路径可以收敛为下表场景推荐路径关键接口主要约束Web 会议内嵌Client View完整自动化ZoomMtg.BreakoutRoom.*全套 APIhost/co-host 角色 会议开启功能Web Component View先确认 API 对等性ZoomMtgEmbedded对应 API不保证与 Client View 对等iOS / AndroidHelper 模型getCreatorHelper/getAdminHelper状态事件需走 delegate 回调Windows / macOSController 模型GetBreakoutRoomsController/getBreakoutRoomsController角色驱动五角色接口会前预分配REST APIPOST /v2/users/{userId}/meetings无法自动开启需会内补一刀Video SDKSubsessionsgetSubsessionClient()全部房间逻辑需自研本文全部事实与代码示例均可溯源到仓库文件主体内容来自 breakout-rooms.md平台上下文来自 meeting-sdk 技能入口、Windows Breakout Rooms 示例、Component View Breakout Rooms 参考、troubleshooting 参考 与 Video SDK Web 技能文档。需要进一步深入某平台的完整生命周期加入、签名、UI 生命周期可沿 meeting-sdk 技能的 Detailed References 索引继续查阅各平台子目录下的 SKILL.md。【免费下载链接】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），仅供参考