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.

IZoomVideoSDK* videoSDK = CreateZoomVideoSDKObj();
if (videoSDK) {
    IZoomVideoSDKSubsessionHelper* subsessionHelper = videoSDK->getSubSessionHelper();
    if (subsessionHelper) {
	    // 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:

  • addSubSessionToPreList(const zchar_t* sSubSessionName); - Add a subsession to the prepared list.
  • getSubSessionPreList - Get the subsession prepared list.
  • removeSubSessionFromPreList(const zchar_t* sSubSessionName) - Remove any subsession from the added prepared list.
  • clearSubSessionPreList - Remove all subsessions from the prepared list.
ZoomVideoSDKErrors err = subsessionHelper->addSubSessionToPreList(L"Subsession to add");
IVideoSDKVector<const zchar_t*>* list = subsessionHelper->getSubSessionPreList();
err = subsessionHelper->removeSubSessionFromPreList(L"Subsession to remove");
err = subsessionHelper->clearSubSessionPreList();

Once you have created the prepared list, 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 know the committed list was created.
  • 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.

ZoomVideoSDKErrors err = subsessionHelper->commitSubSessionList();
IVideoSDKVector<ISubSessionKit*>* list = subsessionHelper->getCommittedSubSessionList();
err = subsessionHelper->withdrawSubSessionList();
virtual void onSubSessionStatusChanged(ZoomVideoSDKSubSessionStatus status, IVideoSDKVector<ISubSessionKit*>* pSubSessionKitList) {
}
// ZoomVideoSDKSubSessionStatus
enum ZoomVideoSDKSubSessionStatus {
    ZoomVideoSDKSubSessionStatus_None,
    ZoomVideoSDKSubSessionStatus_Committed,
    ZoomVideoSDKSubSessionStatus_Withdrawn,
    ZoomVideoSDKSubSessionStatus_Started,
    ZoomVideoSDKSubSessionStatus_Stopping,
    ZoomVideoSDKSubSessionStatus_Stopped,
    ZoomVideoSDKSubSessionStatus_CommitFailed,
    ZoomVideoSDKSubSessionStatus_WithdrawFailed,
    ZoomVideoSDKSubSessionStatus_StartFailed,
    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 ZMVideoSDKSubSessionManager or ZMVideoSDKSubSessionParticipant object upon receiving the respective callback, as the local user will be using its dedicated methods later on.

IZoomVideoSDKSubSessionParticipant* subsessionUser;
IZoomVideoSDKSubSessionManager* subsessionManager;
// Subsession manager role
virtual void onSubSessionManagerHandle(IZoomVideoSDKSubSessionManager* pManager) {
    if (!pManager) { return; }
    subsessionManager = pManager;
}
// Subsession user role
virtual void onSubSessionParticipantHandle(IZoomVideoSDKSubSessionParticipant* pUser) {
    if (!pUser) { return; }
    subsessionUser = pUser;
}

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(const zchar_t* sMessage) - Broadcast a message from the main session to all subsessions. Upon a successful broadcast, the SDK calls the onBroadcastMessage callback.
// Subsession manager role
if (!subsessionManager) { return; }
ZoomVideoSDKErrors startRes = subsessionManager->startSubSession();
ZoomVideoSDKErrors stopReserr = subsessionManager->stopSubSession();
bool isStarted = subsessionManager->isSubSessionStarted();
ZoomVideoSDKErrors err = subsessionManager->broadcastMessage(L"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
if (!subsessionUser) { return; }
ZoomVideoSDKErrors err = subsessionUser->returnToMainSession();
err = subsessionUser->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.

virtual void onSubSessionUsersUpdate(ISubSessionKit* pSubSessionKit) {
    IVideoSDKVector<ISubSessionUser*>* users = 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 ZMVideoSDKSubSessionStatus_Started status, you can identify which ZMVideoSDKSubSessionKit they can join by calling joinSubSession.

ZoomVideoSDKErrors err = subsession->joinSubSession();

Leave subsession

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

ZoomVideoSDKErrors err = 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 for help
ZoomVideoSDKErrors err = subsessionUser->requestForHelp();
// User received back the result
virtual onSubSessionUserHelpRequestResult(ZoomVideoSDKUserHelpRequestResult result) {
}
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 onSubSessionUserHelpRequest callback. The manager can decide what to do with the received ISubSessionUserHelpRequestHandler, which contains the user information and the subsession name.

virtual void onSubSessionUserHelpRequest(ISubSessionUserHelpRequestHandler* pHandler) {
    if (!pHandler) return;
    const zchar_t* name = pHandler->getRequestUserName();
    const zchar_t* subsessionName = pHandler->getRequestSubSessionName();
    ZoomVideoSDKErrors err = pHandler->ignore();
    err = pHandler->joinSubSessionByUserRequest();
}

Chat in subsession

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

More details

For more information, see the IZoomVideoSDKSubSessionHelper Class Reference.