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 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.

val subsessionHelper = ZoomVideoSDK.getInstance().subsessionHelper
if (subsessionHelper.isSubsessionFeatureSupport) {
    // Subsession is supported
}

ZoomVideoSDKSubsessionHelper subsessionHelper = ZoomVideoSDK.getInstance().getSubsessionHelper();
if (subsessionHelper.isSubsessionFeatureSupport()) {
    // Subsession is supported
}

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:

  • 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.
subsessionHelper.getCommittedSubSessionList()
subsessionHelper.withdrawSubSessionList()
subsessionHelper.commitSubSessionList(listOf("Session 1", "Session 2", "Session 3"))
override fun onSubSessionStatusChanged(status: ZoomVideoSDKSubSessionStatus, subSessionKitList: List<SubSessionKit>) {
}
enum class ZoomVideoSDKSubSessionStatus {
    ZoomVideoSDKSubSessionStatus_None,
    ZoomVideoSDKSubSessionStatus_Committed,
    ZoomVideoSDKSubSessionStatus_Withdrawn,
    ZoomVideoSDKSubSessionStatus_Started,
    ZoomVideoSDKSubSessionStatus_Stopping,
    ZoomVideoSDKSubSessionStatus_Stopped,
    ZoomVideoSDKSubSessionStatus_CommitFailed,
    ZoomVideoSDKSubSessionStatus_WithdrawFailed,
    ZoomVideoSDKSubSessionStatus_StartFailed,
    ZoomVideoSDKSubSessionStatus_StopFailed
}

The SDK calls onSubSessionStatusChanged whenever the subsession status changes, including started, stopped, and when a list is committed. The callback returns a ZoomVideoSDKSubSessionStatus value and a list of SubSessionKit objects. Each kit provides the subsession's name, ID, user list, and joinSubSession method.

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.

private lateinit var subsessionUser: ZoomVideoSDKSubSessionParticipant
private lateinit var subSessionManager: ZoomVideoSDKSubSessionManager
// Subsession manager role
override fun onSubSessionManagerHandle(manager: ZoomVideoSDKSubSessionManager) {
    subSessionManager = manager
}
// Subsession user role
override fun onSubSessionParticipantHandle(user: ZoomVideoSDKSubSessionParticipant) {
    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.
// Subsession manager role
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.
// Subsession user role
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 SubSessionKit object.

override fun onSubSessionUsersUpdate(subSessionKit: SubSessionKit) {
    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 ZoomVideoSDKSubSessionStatus_Started status, you can identify which SubSessionKit they can join by calling joinSubSession.

// subSessionKit is an instance of SubSessionKit
subSessionKit.joinSubSession()

Leave subsession

To leave a subsession and return to the main session, call the returnToMainSession method from the previously saved subsessionUser object.

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.

// User requested help
subsessionUser.requestForHelp()
// User received back the result
override fun onSubSessionUserHelpRequestResult(eResult: ZoomVideoSDKUserHelpRequestResult) {
}
public enum ZoomVideoSDKUserHelpRequestResult {
    ZoomVideoSDKUserHelpRequestResult_Idle,
    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.

override fun onSubSessionUserHelpRequest(handler: SubSessionUserHelpRequestHandler) {
    handler.getRequestUserName
    handler.getRequestSubSessionName
    handler.ignore()
    handler.joinSubSessionByUserRequest()
}

Chat in subsession

Users can chat in a subsession. The SDK scopes the chat to the user's subsession.

More details

See the ZoomVideoSDKSubSessionHelper Interface Reference for more details.