Joining a Meeting

Caution

This documentation may no longer be current. Click here to view the updated content on our Developer Portal.

The Meeting Instance

Joining a meeting using the Webex Meetings Web SDK allows you to participate in video conferences. This article guides you through the process of joining a meeting and covers various additional scenarios, including joining with or without media, configuring audio and video settings, and screen sharing.

A Meeting instance represents a specific meeting session within the Webex Meetings SDK. Each meeting has its Meeting instance, which allows you to interact with and control the meeting's behavior.

Fetch a Meeting Instance

A meeting instance is typically created once a meeting is initiated through the SDK. If a meeting has already been created on the SDK, you can retrieve it using the SDK's meetings object by passing a meetingId.

Note

This method does not fetch the list of all meetings from the Webex cloud. It only lists the meetings that are created either with webex.meetings.create or webex.meetings.syncMeetings.

const meeting = webex.meetings.getAllMeetings()[meetingId];

If participants have already joined the meeting, it can be retrieved from Webex Cloud. Refer to Sync Meetings.

Join a Meeting

Once you have a Meeting object, you can join the meeting using the join() method:

const join = await meeting.join(joinOptions);

You can specify options via a joinOptions object, including PSTN, video, and screensharing:

Asynchronous	Yes
Parameters	Name Description Type Mandatory joinOptions A configurable options object for joining a meeting. JoinOptions No
Returns	Promise<JoinResponse>

The join() method returns a JoinResponse object containing comprehensive details about the meeting.

The joinOptions Object

The joinOptions object determines how a participant joins a meeting:

Attribute Name	Description	Type	Optional
resourceId	resourceId of the paired device if joining with a Device.	String	Yes
moveToResource	Moves the meeting to the paired device, if true.	Boolean	Yes
pin	PIN of the Meeting room, if you're joining as a host.	String	Yes
moderator	Indicate if you are joining as a moderator/host.	Boolean	Yes
meetingQuality	Customize meeting video quality settings.	Object	Yes
meetingQuality.local	Set the local video quality. Valid values are: "360p", "480p", "720p", and "1080p".	String	Yes
meetingQuality.remote	Set remote video quality. Valid values are: "LOW", "MEDIUM", and "HIGH".	String	Yes
rejoin	Allow or disallow rejoining the meeting.	Boolean	Yes

Here's a sample joinOptions object:

const joinOptions = {
  pin: '123456',
  moderator: false,
  moveToResource: false,
  resourceId: '31c4a552-4167-49ef-8034-c8dc8c5de76f',
  receiveTranscription: false,
  meetingQuality: {
    local: '720p',
    remote: 'HIGH'
  },
  rejoin: false
};

Join a Meeting Without Media

A participant can join without any media connection initially and can set up media options later as required.

To join a meeting without media:

meeting.join().then(() => {
  // Meeting joined successfully
});

Add Media to a Meeting

To join with a meeting with media enabled, you must create media streams first, before adding the media to the meeting.

Set up Media Streams

To create various MediaStreams object streams like microphone, video, and screen sharing:

const audioVideoConstraints = {
  audio: { deviceId: audioDeviceId },
  video: { deviceId: videoDeviceId }
};

const microphoneStream =
  await webex.meetings.mediaHelpers.createMicrophoneStream(constraints.audio);
const cameraStream = await webex.meetings.mediaHelpers.createCameraStream(
  constraints.video
);
const [localShareVideoStream, localShareAudioStream] =
  await webex.meetings.mediaHelpers.createDisplayStreamWithAudio();

For more info on the MediaStreams object, see Media Streams Management.

The addMedia() method

Once a participant has joined the meeting, the participant's media streams can be added using the addMedia() method:

const addMediaOptions = {
  localStreams: {
    microphone: microphoneStream,
    camera: cameraStream,
  },
  allowMediaInLobby: true,
};

await meeting.addMedia(addMediaOptions);

Asynchronous	Yes
Parameters	Name Description Type Mandatory addMediaOptions A configurable media options object that holds information about the local streams. AddMediaOptions Yes
Returns	Promise<undefined>

To add media, configure the streams using the localStreams attribute in the addMediaOptions object.

The LocalStreams object

The LocalStreams object is a collection of different LocalStream objects that define the media within a meeting context.

The LocalStream serves as a common interface implemented by various classes, each representing different types of media streams. The classes, which include LocalMicrophoneStream, LocalCameraStream, LocalSystemAudioStream, and LocalDisplayStream, implement the LocalStream interface to provide specific functionality for managing various media streams.

The LocalStreams contains the following attributes:

Name	Type	Optional
microphone	LocalMicrophoneStream	Yes
camera	LocalCameraStream	Yes
screenShare.audio	LocalSystemAudioStream	Yes
screenShare.video	LocalDisplayStream	Yes

Join a Meeting with Media

To join a meeting with media enabled, define a joinOptions object and pass it to the Meeting object's join() method:

const joinOptions = {
  enableMultistream: false, // Multistream is an experimental feature
  pin: 'pin',
  moderator: false,
  breakoutsSupported: false, // Enable breakout rooms in the meeting
};

await meeting.join(joinOptions);

See above for information on the joinOptions object.

Update Media for a Meeting

At any time in the meeting, you can remove or add additional media streams using the following methods. While updating a media of the same type (e.g. camera stream), first unpublish the media streams before publishing the new streams.

Add Media Stream

If we already have media added to a meeting, we can add more streams by using the publishStreams() method as follows.

await meeting.publishStreams({camera: cameraStream}));

Asynchronous	Yes
Parameters	Name Description Type Mandatory localStreams A configurable options object for joining a meeting. LocalStreams Yes
Returns	Promise<undefined>

Remove a Media Stream

This method is used to remove a media stream from the meeting.

Asynchronous	Yes
Parameters	Name Description Type Mandatory streams An array of all the streams that need to be unpublished. LocalStream[] Yes
Returns	Promise<undefined>

To remove media streams:

const streamsToUnpublish = [];

if (localMedia.screenShare.audio) {
  streamsToUnpublish.push(screenShare.audio);
}
if (localMedia.screenShare.video) {
  streamsToUnpublish.push(screenShare.video);
}

if (streamsToUnpublish.length) {
  await meeting.unpublishStreams(streamsToUnpublish);
}

Join a Meeting with Media

The joinWithMedia() method lets you join a meeting and add media in a single operation.

Asynchronous	Yes
Parameters	Options Name Description Type Mandatory joinOptions A configurable options object for joining a meeting. JoinOptions No mediaOptions A configurable options object for setting up media. AddMediaOptions No
Returns	Promise<JoinResponse>

Join a meeting using joinOptions and mediaOptions:

const options = {
  joinOptions: {
    pin: '123456',
    moderator: false
  },
  mediaOptions: {
    localStreams: {
      microphone: microphoneStream,
      camera: cameraStream
    }
  }
};

await meeting.joinWithMedia(options);

If the participant is challenged with a PIN/password or made to wait in the lobby, media has to be set up once the participant is added to the meeting. You can then listen to meeting events ([meeting:self:guestAdmitted](https://webex.github.io/webex-js-sdk/api/#meetingeventmeetingselfguestadmitted)) and perform subsequent operations like adding media.

Here are the various scenarios in which the joinOptions object can vary:

Scenario	Description	Parameter Requirement
A	Joining your personal meeting room.	NA
B	Joining someone else's personal meeting room.	Use the host pin to join someone else's PMR as a host and assume host privilegs in the meeting.
C	Joining an unclaimed personal meeting room.	The join will throw an error in this scenario when you try to join without any options.
D	Joining in any other way (SIP, PSTN, conversationUrl, link, etc.)	Only specify resourceId if joining with a device.