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.

In Flutter, all subsession actions are performed through a single ZoomVideoSdkSubSessionHelper. The SDK notifies the local user of their subsession role (manager or user) through event listeners, and the methods available to each role are called on the same helper.

Call the subsession helper

After joining a session, get the subsession helper from the ZoomVideoSdk instance. The subsession methods can be called only by the session's host and managers.

var zoom = ZoomVideoSdk();
var subSessionHelper = zoom.subSessionHelper;

Configure subsessions

Sessions can be configured only by the host.

Call the following methods as needed to create the committed list of subsessions:

commitSubSessionList(List<String> subSessionNames) - Withdraw all committed subsession lists and commit the prepared list. Pass in a list of your subsession names.
getCommittedSubSessionList - Get the committed subsession list. Calling this right after commitSubSessionList will not work, as you will have to wait for the onSubSessionStatusChanged event to get successful creation.
withdrawSubSessionList - Withdraw the committed subsession list.

await subSessionHelper.commitSubSessionList(["Session 1", "Session 2", "Session 3"]);
List<ZoomVideoSdkSubSessionKit> committedList = await subSessionHelper.getCommittedSubSessionList();
await subSessionHelper.withdrawSubSessionList();

The SDK fires the onSubSessionStatusChanged event whenever the subsession status changes, including started, stopped, and when a list is committed. The event data contains a SubSessionStatus value and a list of ZoomVideoSdkSubSessionKit objects. Each kit provides the subsession's name (subSessionName), ID (subSessionId), and user list (subSessionUserList).

final subSessionStatusChanged =
    eventListener.addListener(
        EventType.onSubSessionStatusChanged,
        (data) async {
            data = data as Map;
            String status = data['status'];
            List<ZoomVideoSdkSubSessionKit> subSessions =
            (jsonDecode(data['subSessions']) as List)
            .map((kit) => ZoomVideoSdkSubSessionKit.fromJson(kit))
            .toList();
    },
);

The SubSessionStatus class defines the following status values:

class SubSessionStatus {
    static const String None;
    static const String Committed;
    static const String Withdrawn;
    static const String Started;
    static const String Stopping;
    static const String Stopped;
    static const String CommitFailed;
    static const String WithdrawFailed;
    static const String StartFailed;
    static const String StopFailed;
}

Manage subsessions

The host and managers can manage subsessions from the main session. The SDK fires these events based on the local user's role:

onSubSessionManagerHandle - The local user has the subsession manager role.
onSubSessionParticipantHandle - The local user has the subsession user role.

Listen for these events to determine which set of subsession methods the local user can call on the helper.

final subSessionManagerHandle =
    eventListener.addListener(EventType.onSubSessionManagerHandle, (data) async {
        // The local user has the subsession manager role
    });
final subSessionParticipantHandle =
    eventListener.addListener(EventType.onSubSessionParticipantHandle, (data) async {
        // The local user has the subsession user role
    });

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(String message) - Broadcast a message from the main session to all subsessions.

// Subsession manager role
await subSessionHelper.startSubSession();
await subSessionHelper.stopSubSession();
bool started = await subSessionHelper.isSubSessionStarted();
await subSessionHelper.broadcastMessage("Hello World");

Subsession user

The user role can call the following methods:

returnToMainSession - Leave the 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 receives the onSubSessionUserHelpRequestHandler event. After a manager responds to this request, the subsession user who requested help receives the onSubSessionUserHelpRequestResult event.

// Subsession user role
await subSessionHelper.returnToMainSession();
await subSessionHelper.requestForHelp();

List users in a subsession

Each ZoomVideoSdkSubSessionKit exposes its members through the subSessionUserList property. Each ZoomVideoSdkSubSessionUser object contains the subsession user's userName and userGUID. When subsession users change, the SDK fires the onSubSessionUsersUpdate event and returns an updated ZoomVideoSdkSubSessionKit object.

final subSessionUsersUpdate =
    eventListener.addListener(
        EventType.onSubSessionUsersUpdate,
        (data) async {
            data = data as Map;
            ZoomVideoSdkSubSessionKit subSession =
                ZoomVideoSdkSubSessionKit.fromJson(
                    jsonDecode(data['subSession']));
            List<ZoomVideoSdkSubSessionUser> users =
                subSession.subSessionUserList;
    },
);

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 event with the SubSessionStatus.Started status, you can identify which ZoomVideoSdkSubSessionKit they can join and pass its subSessionId to joinSubSession.

// subSessionKit is an instance of ZoomVideoSdkSubSessionKit
await subSessionHelper.joinSubSession(subSessionKit.subSessionId);

Leave subsession

To leave a subsession and return to the main session, call returnToMainSession.

await subSessionHelper.returnToMainSession();

Request help

All users in subsessions can request that the manager come into their subsession. The manager is notified of these help requests and can take a follow-up action, which is also sent back to the requester.

Subsession user request for help

To request help, the user in a subsession can call requestForHelp to notify and request that the manager come into the subsession. After the manager responds to the request, the user who requested help receives the onSubSessionUserHelpRequestResult event with a UserHelpRequestResult value.

// User requests help
await subSessionHelper.requestForHelp();
// User receives the result
final helpRequestResult =
    eventListener.addListener(EventType.onSubSessionUserHelpRequestResult, (data) async {
        data = data as Map;
        String result = data['result'];
    });

The UserHelpRequestResult class defines the following result values:

class UserHelpRequestResult {
    static const String Idle;
    static const String Busy;
    static const String Ignore;
    static const String HostAlreadyInSubSession;
}

Manager responds to request for help

Whenever a user in a subsession requests help, the manager receives the onSubSessionUserHelpRequestHandler event. The manager can read the requesting user's name and subsession name from the helper, then decide what to do with the request.

final helpRequestHandler =
    eventListener.addListener(EventType.onSubSessionUserHelpRequestHandler, (data) async {
        String userName = await subSessionHelper.getRequestUserName();
        String subSessionName = await subSessionHelper.getRequestSubSessionName();
        // Ignore the request
        await subSessionHelper.ignoreUserHelpRequest();
        // Or join the subsession where help was requested
        await subSessionHelper.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 class reference for more details.