# 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 macOS 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 = ZMVideoSDK.shared().getSubSessionHelper() { // Continue with subsession methods here } ``` ## Configure subsessions Sessions can be configured only by the host. Once you have the subsession names, call the following methods as needed to create the committed list of subsessions: - `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 `ZMVideoSDKSubSessionStatus` value and a list of `ZMVideoSDKSubSessionKit` objects. Each kit contains the subsession's name, ID, user list, and the `joinSubSession` method. ```swift subsessionHelper.getCommittedSubSessionList() subsessionHelper.withdrawSubSessionList() subsessionHelper.commitSubSessionList(["Session 1", "Session 2", "Session 3"]) func onSubSessionStatusChanged(_ status: ZMVideoSDKSubSessionStatus, subSessionKit subSessionKitList: [ZMVideoSDKSubSessionKit]?) { } // ZMVideoSDKSubSessionStatus enum ZMVideoSDKSubSessionStatus { ZMVideoSDKSubSessionStatus_None, ZMVideoSDKSubSessionStatus_Committed, ZMVideoSDKSubSessionStatus_Withdrawn, ZMVideoSDKSubSessionStatus_Started, ZMVideoSDKSubSessionStatus_Stopping, ZMVideoSDKSubSessionStatus_Stopped, ZMVideoSDKSubSessionStatus_CommitFailed, ZMVideoSDKSubSessionStatus_WithdrawFailed, ZMVideoSDKSubSessionStatus_StartFailed, ZMVideoSDKSubSessionStatus_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 `ZMVideoSDKSubSessionManager` or `ZMVideoSDKSubSessionParticipant` object upon receiving the respective callback, as the local user will be using its dedicated methods later on. ```swift var subsessionUser: ZMVideoSDKSubSessionParticipant? var subsessionManager: ZMVideoSDKSubSessionManager? // Subsession manager role public func onSubSessionManagerHandle(_ manager: ZMVideoSDKSubSessionManager?) { guard let manager = manager else { print("Warning: onSubSessionManagerHandle received nil manager.") return } subsessionManager = manager } // Subsession user role public func onSubSessionParticipantHandle(_ user: ZMVideoSDKSubSessionParticipant?) { 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 `onSubSessionUserHelpRequest` 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 user = subsessionUser else { print("Warning: subsessionUser is nil — cannot perform actions.") return } user.returnToMainSession() user.requestForHelp() ``` ### List users in a subsession To list users in a specific subsession, call `getSubSessionUserList`. Each `ZMVideoSDKSubSessionUser` object contains the local subsession user's username and GUID. When subsession users are changed, the SDK calls `onSubSessionUsersUpdate` and returns an updated `ZMVideoSDKSubSessionKit` object. ```swift func onSubSessionUsersUpdate(_ subSessionKit: ZMVideoSDKSubSessionKit?) { subSessionKit?.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 `ZMVideoSDKSubSessionStatus_Started` status, you can identify which `ZMVideoSDKSubSessionKit` they can join by calling `joinSubSession`. ```swift guard status == ZMVideoSDKSubSessionStatus_Started, let subSessionKitList = subSessionKitList else { return } // From the subSessionKitList, identify which 1 of the subSessionKit to join for subSessionKit in subSessionKitList { // Identify which subSessionKit first then join 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 func onSubSessionUserHelpRequestResult(_ result: ZMVideoSDKUserHelpRequestResult) { } enum ZMVideoSDKUserHelpRequestResult { ZMVideoSDKUserHelpRequestResult_Idle, ZMVideoSDKUserHelpRequestResult_Busy, ZMVideoSDKUserHelpRequestResult_Ignore, ZMVideoSDKUserHelpRequestResult_HostAlreadyInSubSession } ``` ### Manager responds to request for help Whenever a user in a subsession requests help, the manager receives the `onSubSessionUserHelpRequest` callback. The manager can decide what to do with the received `ZMVideoSDKSubSessionUserHelpRequestHandler`, which contains the user information and the subsession name. ```swift func onSubSessionUserHelpRequest(_ handler: ZMVideoSDKSubSessionUserHelpRequestHandler) { handler.requestUserName handler.requestSubSessionName handler.ignore() handler.joinSubSessionByUserRequest() } ``` ## Chat in subsession Users can [chat](/docs/video-sdk/macos/chat/) in a subsession. The SDK scopes the chat to the user's subsession. ## More details See the [ZMVideoSDKSubsessionHelper.h File Reference](https://marketplacefront.zoom.us/sdk/custom/macos/_z_m_video_s_d_k_subsession_helper_8h.html) for more details.