Sessions

A session is the most fundamental building block of the Video SDK for Android. A session is similar to but not limited to a virtual meeting where two or more users can communicate with each other over video and audio. You can also include other features in a session, such as chat and screen sharing.

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 SDK 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. See Authorization for details.

• 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 users 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 SDKSessionContext#

val params = ZoomVideoSDKSessionContext().apply {
    sessionName = "My Session"
    userName = "My Name"
    token = "" // TODO: Pass in your JWT. In a production app, ensure that you do not hard code JWT or any confidential credentials.
}

ZoomVideoSDKSessionContext params = new ZoomVideoSDKSessionContext();
params.sessionName = "My Session";
params.userName = "My Name";
params.token = ""; // TODO: Pass in your JWT

Prior to joining a session, ensure that you have implemented an instance of the ZoomVideoSDKDelegate. To successfully monitor events related to a session, you will need to use some important callback functions provided by the delegate.

Once you have your params and listener setup, call the joinSession() method to join a session.

Join a session#

val session = ZoomVideoSDK.getInstance().joinSession(params)

ZoomVideoSDKSession session = ZoomVideoSDK.getInstance().joinSession(params);

Note that the return value of the joinSession() method will only indicate that an attempt will be made to join a session. A successful result here does not mean you are in the session already.

To determine the status after calling joinSession(), you must listen for specific callbacks, some of which may require user interaction.

Once you have obtained the session object, you may also use it to display your video preview. More information on how to do this can be found in the Render User Video section.

Optimize join latency with pre-join#

To reduce connection time in 1:1 calls or invite flows, prepare the session before the user accepts the call. When the user accepts, commit the join to connect immediately. This two-step flow minimizes the time between when a user answers a call and when they're in the call.

Before the user can use prepareJoin() and commitJoin(), the caller must already have the session up and running. The user then uses the pre-join flow to join the existing session more quickly.

Implement the surrounding incoming-call workflow, including push notification delivery and platform-level call handling using a framework like TelecomManager.

Prepare to join#

First create your session context as described in Create SDKSessionContext. Then call prepareJoin() to prepare the connection without joining the session. Configure the timeout interval using ZoomVideoSDKPreJoinParam.

val preJoinParam = ZoomVideoSDKPreJoinParam().apply {
    timeoutInterval = 30 // Timeout in seconds (1-60, or 0 for default 30s)
}

val session = ZoomVideoSDK.getInstance().prepareJoin(params, preJoinParam)

ZoomVideoSDKPreJoinParam preJoinParam = new ZoomVideoSDKPreJoinParam();
preJoinParam.timeoutInterval = 30; // Timeout in seconds (1-60, or 0 for default 30s)

ZoomVideoSDKSession session = ZoomVideoSDK.getInstance().prepareJoin(params, preJoinParam);

Commit the join#

When the user accepts the call, finalize the connection by calling commitJoin().

val result = ZoomVideoSDK.getInstance().commitJoin()

int result = ZoomVideoSDK.getInstance().commitJoin();

The return value indicates success or error. Listen for onSessionJoin() to confirm you've successfully joined.

Cancel pre-join#

If the user declines the call after prepareJoin(), cancel the preparation.

val result = ZoomVideoSDK.getInstance().cancelPrepareJoin()

int result = ZoomVideoSDK.getInstance().cancelPrepareJoin();

Hold participants until admitted#

OnHold places participants in a holding state when they join a session. They stay on hold, outside the session, until a host or manager admits them.

The hold JWT payload field controls whether a session supports OnHold. Set it in the JWT of the first user to join, which starts the session.

• 0 - (default) The session does not support OnHold.
• 1 - The session supports OnHold, and OnHold is on when the session starts.
• 2 - The session supports OnHold, but OnHold is off when the session starts. A host or manager can turn it on during the session.

When OnHold is on, participants who join receive onHoldJoined() instead of onSessionJoin() until a host or manager admits them.

Check OnHold status#

Get the ZoomVideoSDKOnHoldHelper by calling getOnHoldHelper(). Call isSupportHold() to check whether the current session supports OnHold, and isOnHoldEnabled() to check whether OnHold is on.

val onHoldHelper = ZoomVideoSDK.getInstance().onHoldHelper
val isSupportHold = onHoldHelper.isSupportHold()
val isOnHoldEnabled = onHoldHelper.isOnHoldEnabled()

ZoomVideoSDKOnHoldHelper onHoldHelper = ZoomVideoSDK.getInstance().getOnHoldHelper();
boolean isSupportHold = onHoldHelper.isSupportHold();
boolean isOnHoldEnabled = onHoldHelper.isOnHoldEnabled();

Get notified when you are on hold#

When the local user joins a session with OnHold on, the SDK calls onHoldJoined() instead of onSessionJoin(). Use this callback to show a holding screen until a host or manager admits the user. onHoldJoined() means the user is on hold, and onSessionJoin() means the user joined the session.

override fun onHoldJoined() {
    // The local user is on hold. Show a holding screen.
}

@Override
public void onHoldJoined() {
    // The local user is on hold. Show a holding screen.
}

Get notified when other users are on hold#

The SDK calls onHoldUserJoin() when users are placed on hold, and onHoldUserLeave() when users leave the on-hold list. Use these callbacks to keep a list of users waiting for a host or manager to admit them.

Users leave the on-hold list in either of the following cases.

• A host or manager admits them. Hosts and managers then also receive onUserJoin() for each admitted user who is not already in the session's user list.
• They leave while still on hold. The SDK reports these users through onHoldUserLeave() only, not through onUserLeave().

override fun onHoldUserJoin(onHoldHelper: ZoomVideoSDKOnHoldHelper?, userList: MutableList<ZoomVideoSDKOnHoldUser>) {
    userList.forEach {
        // Add it.userName to your list of users on hold.
    }
}

override fun onHoldUserLeave(onHoldHelper: ZoomVideoSDKOnHoldHelper?, userList: MutableList<ZoomVideoSDKOnHoldUser>) {
    // Remove these users from your list of users on hold.
}

@Override
public void onHoldUserJoin(ZoomVideoSDKOnHoldHelper onHoldHelper, List<ZoomVideoSDKOnHoldUser> userList) {
    for (ZoomVideoSDKOnHoldUser user : userList) {
        // Add user.getUserName() to your list of users on hold.
    }
}

@Override
public void onHoldUserLeave(ZoomVideoSDKOnHoldHelper onHoldHelper, List<ZoomVideoSDKOnHoldUser> userList) {
    // Remove these users from your list of users on hold.
}

Admit users on hold#

A host or manager can call getOnHoldUserList() to get the users currently on hold, then call admit() to admit one user or admitAll() to admit every user on hold.

val onHoldHelper = ZoomVideoSDK.getInstance().onHoldHelper

// Admit one user.
onHoldHelper.onHoldUserList.firstOrNull()?.let { user ->
    val result = onHoldHelper.admit(user)
}

// Admit all users on hold.
val result = onHoldHelper.admitAll()

ZoomVideoSDKOnHoldHelper onHoldHelper = ZoomVideoSDK.getInstance().getOnHoldHelper();
List<ZoomVideoSDKOnHoldUser> onHoldUsers = onHoldHelper.getOnHoldUserList();

// Admit one user.
if (onHoldUsers != null && !onHoldUsers.isEmpty()) {
    int result = onHoldHelper.admit(onHoldUsers.get(0));
}

// Admit all users on hold.
int result = onHoldHelper.admitAll();

The return value is ZoomVideoSDKErrors.Errors_Success on success, or an error code otherwise.

Turn OnHold on or off during a session#

A host or manager can call enableHold() to turn OnHold on or off in a session that supports OnHold. This change only affects future join attempts. It does not admit users who are already on hold.

// Pass true to turn OnHold on, or false to turn it off.
val result = ZoomVideoSDK.getInstance().onHoldHelper.enableHold(true)

// Pass true to turn OnHold on, or false to turn it off.
int result = ZoomVideoSDK.getInstance().getOnHoldHelper().enableHold(true);

Obtain session information#

Upon joining a session, you may need to obtain various pieces of information about the session itself. To do this, retrieve an instance of the ZoomVideoSDKSession object through the SDK.

Join a session#

val session = ZoomVideoSDK.getInstance().session
session.sessionName
session.sessionPassword
session.sessionHost
session.sessionHostName

ZoomVideoSDKSession session = ZoomVideoSDK.getInstance().getSession();
session.getSessionName();
session.getSessionPassword();
session.getSessionHost();
session.getSessionHostName();

For a full list of available information on the session object, see the ZoomVideoSDKSession reference.

Leave a session#

To leave a session, you must call leaveSession() and indicate whether or not you would like to end the session if you are the host of the session.

// A value of true will end the session if you are the host
ZoomVideoSDK.getInstance().leaveSession(shouldEndSession)

// A value of true will end the session if you are the host
ZoomVideoSDK.getInstance().leaveSession(shouldEndSession);

Configure audio and video#

When creating or joining a session, you may also choose to configure the audio and video options of the session. This can be done through ZoomVideoSDKAudioOption and ZoomVideoSDKVideoOption respectively.

Configure audio and video options

// Setup audio options
val audioOptions = ZoomVideoSDKAudioOption().apply {
    connect = true // Auto connect to audio upon joining
    mute = true // Auto mute audio upon joining
}
// Setup video options
val videoOptions = ZoomVideoSDKVideoOption().apply {
    localVideoOn = true // Turn on local/self video upon joining
}
// Pass options into session
val params = ZoomVideoSDKSessionContext().apply {
    audioOption = audioOptions
    videoOption = videoOptions
}

// Setup audio options
ZoomVideoSDKAudioOption audioOptions = new ZoomVideoSDKAudioOption();
audioOptions.connect = true; // Auto connect to audio upon joining
audioOptions.mute = true; // Auto mute audio upon joining
// Setup video options
ZoomVideoSDKVideoOption videoOptions = new ZoomVideoSDKVideoOption();
videoOptions.localVideoOn = true; // Turn on local/self video upon joining
// Pass options into session
ZoomVideoSDKSessionContext params = new ZoomVideoSDKSessionContext();
params.audioOption = audioOptions;
params.videoOption = videoOptions;

See Video and Audio for details.

Get user information#

Each user joining a session is represented by an instance of the ZoomVideoSDKUser object. Within this object lives an ID which uniquely identifies the user within the current session.

User information#

While in a session, you can retrieve the following information of a user:

• User
• Display name
• Video status
• Audio status
• Share status
• Video Statistic Information
• Share Statistic Information
• Custom Identity (set on JWT payload)

You can retrieve this information by using the ZoomVideoSDKUser.

Get all users#

To get the information of users, call the getRemoteUsers method in ZoomVideoSDKSession to get an array of all users.

val userList = session.remoteUsers

List<ZoomVideoSDKUser> userList = session.getRemoteUsers();

User roles and actions#

People in a session can hold one of the following roles: host, manager, or participant.

Host#

The user with the host role_type is the host of the session.

A host of the session has the following privileges.

• View information of users in the session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Transfer the host role to someone else in the session.
• Promote another user to be a manager of the session.
• Remove participants from the session.
• Revoke manager privilege from a user.
• Start a live stream.
• Prevent other users from sharing their screen (lock screen).
• End the session.

Manager#

The manager or co-host role can be assigned to a participant by the host to help the host to manage the session participants.

A manager of the session is assigned the following subset of the host privileges.

• Remove participants from a session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Prevent other users from sharing their screen (lock screen).

Participant#

A regular user who joins the session without host or manager permission. A participant has privileges to view their own information as well as the information of other users.#

Manage users#

See below for details on how to manage users.

Change display name#

If you are the host, you can change your display name while in the session using the changeName method. If you are the host or manager, you may also change the display name of other users.

userHelper.changeName("MyName", user)

userHelper.changeName("MyName", user);

Transfer host privilege to another user#

If you are the host of a session, you may transfer your host role to another user.

userHelper.makeHost(user)

userHelper.makeHost(user);

Assign manager privilege to another user#

Managers can help the session host to manage the users. If the host would like to promote a user to be a manager, the following interface must be used to assign a user to be a manager:

Please note that if a user is already a host or a manager, re-assigning will have no impact.

userHelper.makeManager(user)

userHelper.makeManager(user);

Revoke manager privilege#

The host can revoke the manager role from a user by using the following method.

userHelper.revokeManager(user)

userHelper.revokeManager(user);

Remove user from a session#

Users with either host or manager privilege can remove users from a session.

userHelper.removeUser(user)

userHelper.removeUser(user);

Callbacks#

All of these callbacks can be found within your ZoomVideoSDKDelegate implementation. See Integrate for details.

• onSessionNeedPassword - Called when a user is trying to join a session which requires a password. The handler.inputSessionPassword method will allow the user to attempt to join this session with the password provided into this method. After calling this method, you will still need to listen for additional callbacks related to joining the session such as onSessionJoin to determine whether or not the user joined the session.
• onSessionJoin - Called when you have successfully joined the session.
• onHoldJoined - Called when you join a session with OnHold on and are placed on hold. See Hold participants until admitted.
• onHoldUserJoin - Called when users are placed on hold.
• onHoldUserLeave - Called when users leave the on-hold list, either because a host or manager admitted them or because they left while on hold.
• onSessionPasswordWrong - Called if the last password entered was incorrect. The user may attempt to enter the password again through the same method described in onSessionNeedPassword. Alternatively, the user may stop trying to enter the session by calling handler.leaveSessionIgnorePassword() method.
• onError - Called when an error has occurred. See Integrate for a list of errors.

The following are some examples of callbacks you can use for session events.

Get notified when users join a session#

override fun onUserJoin(userHelper: ZoomVideoSDKUserHelper?, userList: MutableList<ZoomVideoSDKUser>) {
    userList.forEach {
        // Access user info for each user that has joined
    }
}

@Override
public void onUserJoin(ZoomVideoSDKUserHelper userHelper, List<ZoomVideoSDKUser> userList) {
    for (ZoomVideoSDKUser user : userList) {
        // Access user info for each user that has joined
    }
}

Get notified when users leave a session#

override fun onUserLeave(userHelper: ZoomVideoSDKUserHelper?, userList: MutableList<ZoomVideoSDKUser>) {
    userList.forEach {
        // Access user info for each user that has left
    }
}

@Override
public void onUserLeave(ZoomVideoSDKUserHelper userHelper, List<ZoomVideoSDKUser> userList) {
    for (ZoomVideoSDKUser user : list) {
        // Access user info for each user that has left
    }
}

Get notified when the host of the session is changed#

override fun onUserHostChanged(userHelper: ZoomVideoSDKUserHelper?, userInfo: ZoomVideoSDKUser?) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

@Override
public void onUserHostChanged(ZoomVideoSDKUserHelper userHelper, ZoomVideoSDKUser userInfo) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

Get notified when a user attempts to join a session without entering a required password#

override fun onSessionNeedPassword(handler: ZoomVideoSDKPasswordHandler?) {
    // Try entering password again
    handler?.inputSessionPassword("anotherPassword")
    // Leave the session without trying
    handler?.leaveSessionIgnorePassword()
}

@Override
public void onSessionNeedPassword(ZoomVideoSDKPasswordHandler handler) {
    // Try entering the password again
    handler.inputSessionPassword("anotherPassword");
    // Leave the session without trying
    handler.leaveSessionIgnorePassword();
}

Get notified when a user enters an incorrect password while attempting to join a session#

override fun onSessionPasswordWrong(handler: ZoomVideoSDKPasswordHandler?) {
    // Try entering password again
    handler?.inputSessionPassword("anotherPassword")
    // Leave the session without trying
    handler?.leaveSessionIgnorePassword()
}

@Override
public void onSessionPasswordWrong(ZoomVideoSDKPasswordHandler handler) {
    // Try entering the password again
    handler.inputSessionPassword("anotherPassword");
    // Leave the session without trying
    handler.leaveSessionIgnorePassword();
}

Get notified when you have successfully joined the session#

override fun onSessionJoin() {
    // You have successfully joined the session
}

@Override
public void onSessionJoin() {
    // You have successfully joined the session
}

Get notified when you have successfully left the session#

override fun onSessionLeave() {
    // You have successfully left the session
}

@Override
public void onSessionLeave() {
    // You have successfully left the session
}

Get notified when the current user is the new host#

override fun onUserManagerChanged(user: ZoomVideoSDKUser) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

@Override
public void onUserManagerChanged(ZoomVideoSDKUser zoomVideoSDKUser) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

Get notified when the user name changed#

override fun onUserNameChanged(user: ZoomVideoSDKUser) {
    // Recommended action: get new username and update UI if applicable
}

@Override
public void onUserNameChanged(ZoomVideoSDKUser zoomVideoSDKUser) {
    // Recommended action: get new username and update UI if applicable
}