Create, Join and Leave a Session


A session is the most fundamental building block of the Video SDK. 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. Optionally, you can also include features such as in-session chat and screen share in a session.

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 ZoomInstantSDKSessionContext and provide the userName, sessionName, and JWT as shown below.

Create SDKSessionContext
val params = ZoomInstantSDKSessionContext().apply {
    sessionName = “My Session”
    userName = “My Name”
    token = “” // TODO: Pass in your JWT. In a prooduction app, ensure that you do not hardcode JWT or any confidential credentials.
}

The following table describes the properties of the ZoomInstantSDKSessionContext object.

Name Required Note
sessionName Yes Name of the session that uniquely identifies the session. A user will be able to join the session by entering the session name. Name should be alphanumeric with a max-length of 200 characters.
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 `ZoomInstantSDKAudioOptions`.
videoOption No Configure video settings by storing values in `ZoomInstantSDKVideoOptions`.

Prior to joining a session, ensure that you have implemented an instance of the IZoomInstantSDKDelegate.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 result = ZoomInstantSDK.getInstance().joinSession(params)
if (result == ZoomInstantSDKErrors.Errors_Success) {
    // Your join session request will be executed, listen for result callbacks
}

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.

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 ZoomInstantSDKSession object through the SDK.

Join a Session
val session = ZoomInstantSDK.getInstance().session
session.sessionName
session.sessionPassword
session.sessionHostId
session.sessionHostName

For a full list of available information on the session object, refer to the ZoomInstantSDKSession reference documentation.

Important Callbacks

All of these callbacks can be found within your ZoomInstantSDKDelegate implementation. For information on how to implement this and add it to the SDK, refer to the Listen for Callback Events guide.

  • 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.

  • 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 error code documentation for more information.

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.

Leave a Session
// A value of true will end the session if you are the host
ZoomInstantSDK.getInstance().leaveSession(shouldEndSession)

Additional Options

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 ZoomInstantSDKAudioOption and ZoomInstantSDKVideoOption respectively.

Configure Audio and Video Options
// Setup audio options
val audioOptions = ZoomInstantSDKAudioOption().apply {
    connect = true // Auto connect to audio upon joining
    mute = true // Auto mute audio upon joining
}
// Setup video options
val videoOptions = ZoomInstantSDKVideoOption().apply {
    localVideoOn = true // Turn on local/self video upon joining
}
// Pass options into session
val params = ZoomInstantSDKSessionContext().apply {
    audioOption = audioOptions
    videoOption = videoOptions
}

Need help?

The first place to look is on our Developer Forum. If you can't find the answer or your request includes sensitive information, contact Developer Support.