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.

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.

await zoom.subSession.commitSubSessionList([
    "Session 1",
    "Session 2",
    "Session 3",
]);
await zoom.subSession.getCommittedSubSessionList();
await zoom.subSession.withdrawSubSessionList();

The SDK calls onSubSessionStatusChanged whenever the committed subsession lists change. The callback returns a SubSessionStatus value and a list of SubSessionKit objects. Each kit provides the subsession's name, ID, and user list.

const subSessionStatusChangedListener = zoom.addListener(
  EventType.onSubSessionStatusChanged,
  ({status, subSessionKitList}: {status: any; subSessionKitList: SubSessionKit[]}) => {
    switch (status) {
      case 'Started':
      // ...
      case 'Stopped':
      // ...
      case 'Stopping':
      // ...
      case 'Committed':
      // ...
      case 'Withdrawn':
      // ...
      case 'WithdrawFailed':
      // ...
      case 'CommitFailed':
      // ...
      case 'StartFailed':
      // ...
      case 'StopFailed':
      // ...
      default:
      // ...
    }
  }
);

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.

const subSessionManagerHandleListener = zoom.addListener(
    EventType.onSubSessionManagerHandle,
    () => {
        // ...
    },
);
const subSessionUserHandleListener = zoom.addListener(
    EventType.onSubSessionParticipantHandle,
    () => {
        // ...
    },
);

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

// Subsession manager role
await zoom.subSession.startSubSession();
await zoom.subSession.stopSubSession();
await zoom.subSession.isSubSessionStarted();
await zoom.subSession.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. See request help for details.

// Subsession user role
await zoom.subSession.returnToMainSession();
await zoom.subSession.requestForHelp();

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.

await zoom.subSession.joinSubSession(subSessionID);

Leave subsession

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

await zoom.subSession.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
await zoom.subSession.requestForHelp();
// User received back the result
const subSessionUserHelpRequestResultListener = zoom.addListener(
  EventType.onSubSessionUserHelpRequestResult,
  ({status}: {status: UserHelpRequestResult}) => {
    switch (status) {
      case UserHelpRequestResult.Idle:
      // ...
      case UserHelpRequestResult.Busy:
      // ...
      case UserHelpRequestResult.Ignore:
      // ...
      case UserHelpRequestResult.HostAlreadyInSubSession:
      // ...
      default:
      // ...
    }
  }
);

Manager responds to request for help

Whenever a user in a subsession requests help, the manager receives the onSubSessionUserHelpRequestHandler callback.

const subSessionUserHelpRequestListener = zoom.addListener(
    EventType.onSubSessionUserHelpRequest,
    async () => {
        // Get user and sub-session information
        // const requestUserName = await zoom.subSession.getRequestUserName();
        // const requestSubSessionName = await zoom.subSession.getRequestSubSessionName();
        // The host can ignore the request
        // await zoom.subSession.ignore();
        // The host can join the sub-session to help the user
        // await zoom.subSession.joinSubSessionByUserRequest();
    },
);

Chat in subsession

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