# Subsessions Subsessions allow you to create separate sessions that users can choose to join. This is similar to the breakout room feature in Zoom Meetings. A Video SDK for iOS session can have up to 50 subsessions. ## Call the subsession helper After joining a session, call `getsubSessionHelper` to get the subsession helper. This method can be called only by the session's host and manager. ```swift if let subsessionHelper = ZoomVideoSDK.shareInstance()?.getsubSessionHelper() { // Continue with subsession methods here } ``` ## Configure subsessions Sessions can be configured only by the host. To prepare the subsession list, call the following methods as needed: - `addSubSession(toPreList: "Array of subsession names")` - Add subsessions to the prepared list and pass in an array of your subsession names. - `getSubSessionPreList` - Get the added subsession prepared list. - `removeSubSession(fromPreList: "Array of subsession names")` - Remove any subsessions from the added prepared list. - `clearSubSessionPreList` - Remove all subsessions from the added prepared list. ```swift subsessionHelper.addSubSession(toPreList: ["Subsession 1", "Subsession 2", "Subsession 3"]) subsessionHelper.getSubSessionPreList() subsessionHelper.removeSubSession(fromPreList: ["Subsession 3"]) subsessionHelper.clearSubSessionPreList() ``` Once you are satisfied with the prepared list and ready to create the committed list, call the following methods as needed: - `commitSubSessionList` - Withdraw all committed subsession lists and commit the prepared list. - `getCommittedSubSessionList` - Get the committed subsession list. Calling this right after `commitSubSessionList` will not work, as you will have to wait for the `onSubSessionStatusChanged` callback to get successful creation. - `withdrawSubSessionList` - Withdraw the committed subsession list. The SDK calls `onSubSessionStatusChanged` whenever the committed subsession lists change. The callback returns a `ZoomVideoSDKSubSessionStatus` value and a list of `ZoomVideoSDKSubSessionKit` objects. Each kit provides the subsession's name, ID, user list, and `joinSubSession` method. ```swift subsessionHelper.commitSubSessionList() subsessionHelper.getCommittedSubSessionList() subsessionHelper.withdrawSubSessionList() public func onSubSessionStatusChanged(_ status: ZoomVideoSDKSubSessionStatus, subSession pSubSessionKitList: [ZoomVideoSDKSubSessionKit]) { } // ZoomVideoSDKSubSessionStatus enum ZoomVideoSDKSubSessionStatus { case ZoomVideoSDKSubSessionStatus_None, case ZoomVideoSDKSubSessionStatus_Committed, case ZoomVideoSDKSubSessionStatus_Withdrawn, case ZoomVideoSDKSubSessionStatus_Started, case ZoomVideoSDKSubSessionStatus_Stopping, case ZoomVideoSDKSubSessionStatus_Stopped, case ZoomVideoSDKSubSessionStatus_CommitFailed, case ZoomVideoSDKSubSessionStatus_WithdrawFailed, case ZoomVideoSDKSubSessionStatus_StartFailed, case ZoomVideoSDKSubSessionStatus_StopFailed, } ``` ## Manage subsessions The host and managers can manage subsessions from the main session. The SDK calls these callbacks based on the following scenarios: - `onSubSessionManagerHandle` - The local user has the subsession manager role. - `onSubSessionParticipantHandle` - The local user has the subsession user role. We recommended that you save an instance of the `ZoomVideoSDKSubSessionManager` or `ZoomVideoSDKSubSessionParticipant` object upon receiving the respective callback, as the local user will be using its dedicated methods later on. ```swift var subsessionUser: ZoomVideoSDKSubSessionParticipant? var subsessionManager: ZoomVideoSDKSubSessionManager? // Subsession manager role public func onSubSessionManagerHandle(_ manager: ZoomVideoSDKSubSessionManager?) { guard let manager = manager else { print("Warning: onSubSessionManagerHandle received nil manager.") return } subsessionManager = manager } // Subsession user role public func onSubSessionParticipantHandle(_ user: ZoomVideoSDKSubSessionParticipant?) { guard let user = user else { print("Warning: onSubSessionParticipantHandle received nil user.") return } subsessionUser = user } ``` ### Subsession manager Both the main session's host and managers hold the subsession manager role. The subsession manager role can call the following methods: - `startSubSession` - Start subsessions. - `stopSubSession` - Stop subsessions. - `isSubSessionStarted` - Determine if subsessions have started. - `broadcastMessage(message: String)` - Broadcast a message from the main session to all subsessions. Upon a successful broadcast, the SDK calls the `onBroadcastMessage` callback. ```swift // Subsession manager role guard let subsessionManager = subsessionManager else { return } subsessionManager.startSubSession() subsessionManager.stopSubSession() subsessionManager.isSubSessionStarted() subsessionManager.broadcastMessage("Hello World") ``` ### Subsession user The user role can call the following methods: - `returnToMainSession` - Leave subsession and return to the main session. - `requestForHelp` - Request the manager's help. This can be used to notify and request that a manager come into the subsession. The manager will receive the `onSubSessionUserHelpRequestHandler` callback. After a manager responds to this request, the subsession user who requested help will receive the `onSubSessionUserHelpRequestResult` callback. ```swift // Subsession user role guard let subsessionUser = subsessionUser else { return } subsessionUser.returnToMainSession() subsessionUser.requestForHelp() ``` ### List users in a subsession To list users in a specific subsession, call `getSubSessionUserList`. Each `ZoomVideoSDKSubSessionUser` object contains the local subsession user's username and GUID. When subsession users are changed, the SDK calls `onSubSessionUsersUpdate` and returns an updated `ZoomVideoSDKSubSessionKit` object. ```swift public func onSubSessionUsersUpdate(_ pSubSessionKit: ZoomVideoSDKSubSessionKit) { pSubSessionKit.getSubSessionUserList() } ``` ## Navigate subsessions Users can navigate across different subsessions. ### Join subsession Hosts and managers can't assign users to subsessions, but users can join a subsession once it has started. You can offer them a choice of which subsession to join. Upon receiving the `onSubSessionStatusChanged` callback with the `ZoomVideoSDKSubSessionStatus_Started` status, you can identify which `ZoomVideoSDKSubSessionKit` they can join by calling `joinSubSession`. ```swift // subSessionKit is an instance of ZoomVideoSDKSubSessionKit subSessionKit.joinSubSession() ``` ### Leave subsession To leave a subsession and return to the main session, call the `returnToMainSession` method from the previously saved `subsessionUser` object. ```swift subsessionUser?.returnToMainSession() ``` ## Request help All users in subsessions can request that the manager come into their subsession. The manager will be notified of these help requests and can take a follow-up action, which will also be sent back to the requester. ### Subsession user request for help To request help, the user in a subsession can send a `requestForHelp` call to notify and request that the manager come into the subsession. After the manager responds to the request, the user who requested help will receive the `onSubSessionUserHelpRequestResult` callback. ```swift // User requested help subsessionUser?.requestForHelp() // User received back the result public func onSubSessionUserHelpRequestResult(_ result: ZoomVideoSDKUserHelpRequestResult) { } enum ZoomVideoSDKUserHelpRequestResult { ZoomVideoSDKUserHelpRequestResult_Idle = 0, ZoomVideoSDKUserHelpRequestResult_Busy, ZoomVideoSDKUserHelpRequestResult_Ignore, ZoomVideoSDKUserHelpRequestResult_HostAlreadyInSubSession } ``` ### Manager responds to request for help Whenever a user in a subsession requests help, the manager receives the `onSubSessionUserHelpRequestHandler` callback. The manager can decide what to do with the received `ZoomVideoSDKSubSessionUserHelpRequestHandler`, which contains the user information and the subsession name. ```swift public func onSubSessionUserHelpRequestHandler(_ pHandler: ZoomVideoSDKSubSessionUserHelpRequestHandler) { pHandler.getRequestUserName() pHandler.getRequestSubSessionName() pHandler.ignore() pHandler.joinSubSessionByUserRequest() } ``` ## Chat in subsession Users can [chat](/docs/video-sdk/ios/chat/) in a subsession. The SDK scopes the chat to the user's subsession. ## More details See the [ZoomVideoSDKSubSessionHelper Class Reference](https://marketplacefront.zoom.us/sdk/custom/ios/interface_zoom_video_s_d_k_sub_session_helper.html) for more details.