Create, join, and leave a session

Sessions are the fundamental building blocks of the Video SDK. A session connects two or more users to communicate with each other over video and audio, similar to a virtual meeting. Optional features include in-session chat, screen share, and live streaming.

Create and join a session

To create a session, you must provide a session name to uniquely identify it.

The process of creating and joining a session requires the developer’s JWT. When you create and join a session through the Video SDK, you must provide a string value representing the session name. The name determines whether the SDK joins an existing session or creates a new one.

  • If you call joinSession() with a session name and there is no session currently active with that name, the SDK creates the session for you.
  • If a session with that name is currently active, the SDK lets you join the active session if you provide all the required parameters, for example, a password if one has been set for the session.

Sessions become inactive and available for reuse after you call leaveSession() to end a session or the backend closes the session when there are no longer any participants in that session.

The session name only needs to be unique to your app at the developer account level. For instance, developers with separate developer accounts (separate SDK credentials) can use the same session name for their separate apps (for example, App A and App B). While the names are the same, Zoom creates different unique sessions for both of these apps. Two different apps built with the Video SDK cannot join sessions created by the other. Each app can only join a session that it created.

To create a session through the SDK, create an instance of ZoomVideoSDKSessionContext and provide the userName, sessionName, and JWT as shown below.

Create a ZoomVideoSDKSessionContext object
ZoomVideoSDKSessionContext sessionContext;
sessionContext.sessionName = L"Session name";
sessionContext.sessionPassword = L"Session password";
sessionContext.userName = L"User name";

// JWT for this session.
sessionContext.token = L"JWT";

// Video and audio options.
sessionContext.videoOption.localVideoOn = true;
sessionContext.audioOption.connect = true;
sessionContext.audioOption.mute = false;

The following table describes all the properties of the ZoomVideoSDKSessionContext object.

Name Required Note
sessionName Yes Name and unique identifier of the session. A user will be able to join the session by entering the session name. Should be alphanumeric with a max-length of 150 characters. It can include symbols and the space character. See the tpc value in the JWT payload in Authentication for details.
userName Yes Display name of the user shown in the session. If empty, this display name will be shown as “null”. It does not have any length limits.
token Yes JWT token generated from your SDK credentials, for more details, refer to the Authentication guide.
sessionPassword No Password for session. If set, the session will be private and can only be joined if the user provides a valid password. If not set, the session will be public and anyone with the session name will be able to join the session. The field has a max-length limit of 10 characters.
audioOption No Configure audio settings by storing values in `ZoomVideoSDKAudioOption`.
videoOption No Configure video settings by storing values in `ZoomVideoSDKVideoOption`.

Prior to joining a session, ensure that you have set up a delegate for callback events by conforming your class to the IZoomVideoSDKDelegate interface.

Once you have your context and delegate set up, call the joinSession() method to join a session.

IZoomVideoSDKSession* pSession = m_pVideoSDK->joinSession(sessionContext);
if (!pSession)
{
	CString cstrInfo;
	cstrInfo.Format(_T("Failed to join session"));
} 
else 
{
    CString cstrInfo;
	cstrInfo.Format(_T("Joined session successfully."));
}

Note that the return value of the joinSession() method will return the session upon success, and NULL upon failure.

Important Callbacks

All of these callbacks can be found within your IZoomVideoSDKDelegate implementation. For information on implementation, refer to the listen for callback events guide.

  • onSessionJoin(): This is called when current user has joined the session.

  • onSessionLeave(): This is called when current user has left the session.

  • onError(ZoomVideoSDKErrors errorCode, int detailErrorCode): This is called when the SDK raises an error. For example, failure to join a session, network timeouts, etc. ZoomVideoSDKErrors_Success represents a successful callback without errors.

  • onUserJoin(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList): This is called when any user joins the session. Helper is provided to provide user-related functionality. userList represents the updated list of users who just joined the session.

  • onUserLeave(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList): This is called when any user leaves the session. Helper is provided to provide user-related functionality. UserList represents the updated list of users who just left the session.

  • onSessionNeedPassword(IZoomVideoSDKPasswordHandler* handler): This is called when attempting to join a session that requires a password, but no password was provided. A handler parameter is provided to retry the join. Use handler when you would like to retry joining the session. Through the IZoomVideoSDKPasswordHandler interface, call inputSessionPassword to pass in the password. Call leaveSessionIgnorePassword to not provide a password and leave the session instead.

  • onSessionPasswordWrong(IZoomVideoSDKPasswordHandler* handler): This is called when attempting to join a session that requires a password, but the provided password was incorrect. A handler parameter is provided to retry the join. Use handler when you would like to retry joining the session. Through the IZoomVideoSDKPasswordHandler interface, call inputSessionPassword to pass in the password. Call leaveSessionIgnorePassword to not provide a password and leave the session instead.

Leave a session

When you are ready to leave the session, call the leaveSession method. Leave session has a bool parameter that when set to true will end the session. Note, only the host can end the session.

// A value of true will end the session, if you are the host.
m_pVideoSDK->leaveSession(false);