Javascript APIs

Introduction

The Javascript API allows you to interact with the meeting room and the meeting Web Components. You may mute a participant, receive the participants list, listen to events and send custom events, etc.

The API can used directly or through messages posted between the parent window and the meeting room iFrame.

Basics

The APIs will only be available once the meeting room was fully loaded. Therefore, you need to listen to wlvmrApiReady callback on the window object before you can call any other APIs or listen to events. The wlvmrApiReady will pass you a handler string under which the main APIs are registerd:

You may register to API events with on(event: MeetingRoomApiEvent, callback: ApiEventCallback): void; and react upon them.

API methods are available through the window[handler] object.

Example

This example code shows you how to wait for the meeting room to be ready, how to subscribe for meeting room events and how to call meeting room APIs:

window["wlvmrApiReady"] = (handler) => {
  if (!window[handler]) {
    console.error(`Handler window.${handler} not found!`);
    return;
  }

  console.log(`Handler window.${handler} ready`)

  window[handler].on("beforeConnecting", (payload) => {
    console.log(`[WLVMR API] - Received event 'beforeConnecting' with payload ${payload}`)
  });

  window[handler].on("participantsUpdated", (payload) => {
    console.log(`[WLVMR API] - Received event 'participantsUpdated' with payload ${JSON.stringify(payload)}`)
  });

  window[handler].on("chatMessage", (payload) => {
    console.log(`[WLVMR API] - Received event 'chatMessage' with payload ${JSON.stringify(payload)} `)
  });

  // Register other event listeners here

  // Call APIs methods on the handler
  window[handler].setAudioInputDeviceId("default", false);
  window[handler].setAudioOutputDeviceId("default", false);
  window[handler].setVideoInputDeviceId("default", true);
}

Javascript API

The following structure defines all APIs available to developers.

interface IMeetingRoomApi {
  // Returns the current Veeting version string, i.e. 6.8.0
  getVersion(): string;
  // Returns the current participants list
  getParticipantsList(): IApiParticipant[];
  // Enables follow me (requires moderator rights)
  enableFollowMe(enabled: boolean): void;
  // Mutes video
  muteVideo(muted: boolean): void;
  // Mutes audio
  muteAudio(muted: boolean): void;
    // Sets the media stream constraints for getUserMedia calls. 
  // If merge is true then mediaStreamConstraints will be merged with the internal constraints
    setMediaStreamConstraints(mediaStreamConstraints: MediaStreamConstraints, merge?: boolean /*default = true*/): void;  
  // Will be ignored if the user is currently connected.
  // Users will automatically be connected when they join the meeting 
  connect(audioOnly: boolean /*default false*/): void;
  // Will be ignored if the user is currently disconnected
  // "connected" refers to the WebRTC streams only. Users can participate on 
  // the whiteboard even though they are disconnected
  disconnect(): void;
  // Sets the video input device. Note: the API does not verify if the device id's are valid
  setVideoInputDeviceId(deviceId: string, reconnect: boolean /*default false*/): void;
  // Sets the audio input device. Note: the API does not verify if the device id's are valid
  setAudioInputDeviceId(deviceId: string, reconnect: boolean /*default false*/): void;
  // Sets the audio output device. Note: the API does not verify if the device id's are valid
  // At the moment only the Chrome and Edge browsers support this API
  setAudioOutputDeviceId(deviceId: string, reconnect: boolean /*default false*/): void;
  // Sets the main video resolution
  setVideoResolution(resolution: MeetingRoomVideoResolution, reconnect: boolean /*default false*/): void;
  // Retrieves the currently selected media devices
  getMediaDeviceSettings(): IMediaDeviceSettings;
  // Electron applications may want to intercept screensharing requests by users
  // This allows the Electron application to pre-select a device ID
  setScreensharingInterceptor(callback: () => void): void;
  // To be used with the screensharing interceptor, throws error if no interceptor set
  startScreensharing(sourceId?: string): void;
  // To be used with the screensharing interceptor, throws error if no interceptor set
  stopScreensharing(): void;
  // works only if partially recorded is configured for this meeting (meeting.recordingType === 'partial')
  startRecording(): void;
  // works only if partially recorded is configured for this meeting (meeting.recordingType === 'partial')
  stopRecording(): void;
  // Only allowed by a moderator. The event will be blocked by the server if called by a non-moderator
  forceStopScreensharing(): void;
  // This fails in most browsers except Google Chrome: entering fullscreen requires a user interaction
  enterVideoFullscreen(): void;
  // Sends a group chat message 
  sendChatMessage(message: string): void;
  // Sends a private chat message to the participant with the ID participantId
  sendPrivateChatMessage(message: string, participantId: string): void;
  // Sends a custom message to all participants
  sendCustomMessage(message: ICustomMessage): void;
  // Disconnects from the server and leaves the meeting room
  leaveMeeting(): void;
  // Allows API users to define how the videos are displayed
  // See separate documentation for more details
  setVideoDisplayCalculator(videoDisplayCalculator: IVideoDisplayCalculator): void;
  // Event listener for meeting room events
  on(event: MeetingRoomApiEvent, callback: ApiEventCallback): void;
}

Type definitions

The following input and output types are used to interact with the Javascript API

Interfaces

interface IApiParticipant {
  id: string;
  name: string;
  joinedAt: number;
  muted?: boolean;
  handRaised?: boolean;
  fromPSTN?: boolean;
  hasVideo?: boolean;
  hadVideo?: boolean;
}

interface IApiChatMessage {
  fromParticipantId: string;
  fromParticipantName: string;
  message: string;
}

interface IApiRemainingTimeUpdate {
  remainingSeconds: number;
}

interface IScreenshareState {
  active: boolean;
}

interface IMediaDeviceSettings {
  videoResolution: string;
  audioInputDeviceId: string;
  audioOutputDeviceId: string;
  videoInputDeviceId: string;
}

interface IVideoPosition {
  participantId: string;
  width: number;
  height: number;
  top: number;
  left: number;
  zIndex: number;
  // Important: CSS class names MUST be prefixed with 'video-container-'
  cssClasses?: string[]
}

interface IVideoDisplayConfig {
  videoPositions: IVideoPosition[],
  hiddenContainers: boolean[]
}

interface IVideoDisplayCalculator {
  calculatePositions(
    containerWidth: number,
    containerHeight: number,
    secondaryPosition: SecondaryVideoPosition,
    secondaryDisplay: SecondaryDisplay,
    secondarySize: SecondaryVideoSize,
    primaryParticipants: string[],
    secondaryParticipants: string[],
    participantsOrder: string[],
    hasSelfView: boolean,
    isSelfviewInSecondary: boolean,
    isTVMode: boolean
  ): IVideoDisplayConfig;
}


interface IMeetingRoomConfig {
  isNamedRoom: boolean;
  meetingId: string;
  roomId: string;
  id: string;
  topic: string;
  meetingType: MeetingType;
  dialInEnabled: boolean;
  passwordProtected: boolean;
  hasVideo: boolean;
  startTime: number;
  endTime: number;
  isOpen: boolean;
  isPreOpen: boolean;
  isClosed: boolean;
  isActive: boolean;
  isDemoMeeting: boolean;
  isPromoMeeting: boolean;
  isFreeMeeting: boolean;
  isRecorded: boolean;
  isAccountValid: boolean;
  maxNumberOfParticipants?: number;
  organizerId: string;
  accountId: string;
  logoFileName?: string;
  disableLogs?: boolean;
  broadcastingEnabled?: boolean;
  participantsEmail?: Availability;
  authType?: MeetingRoomAuthType;
  meetingRoomLayout?: MeetingRoomLayout;
  joinMeetingSound?: string;
  leaveMeetingSound?: string;
  closingMeetingSound?: string;
  closedMeetingSound?: string;
}

interface ICustomMessage {
  from?: string;
  to?: string;
  data?: any;
  onlyToModerators?: boolean;
}

Enums

enum MeetingRoomApiEvent {
  beforeConnecting = "beforeConnecting",
  serverConnected = "serverConnected", // WebRTC connection established
  connected = "connected", // WebRTC connection established
  disconnected = "disconnected", // WebRTC connection disconnected
  leave = "leave",
  participantsUpdated = "participantsUpdated",
  chatMessage = "chatMessage",
  privateChatMessage = "privateChatMessage",
  meetingDurationUpdated = "meetingDurationUpdated",
  meetingRoomConfigUpdated = "meetingRoomConfigUpdated",
  customMessage = "customMessage",
  screenshareStateChange = "screenshareStateChange"
}

enum SecondaryVideoSize {
  small = 0.15,
  large = 0.5
}

enum MeetingRoomVideoResolution {
  "1280x960" = "1280x960",
  "1280x720" = "1280x720",
  "960x720" = "960x720",
  "960x540" = "960x540",
  "640x480" = "640x480",
  "640x360" = "640x360",
  "320x240" = "320x240",
  "320x180" = "320x180",
  "160x120" = "160x120"
}

enum MeetingType {
  standard = "standard",
  offTheRecord = "offTheRecord",
  boardroom = "boardroom",
  classroom = "classroom",
  audiobridge = "audiobridge"
}

enum MeetingRoomLayout {
  classic = "classic",
  presentation = "presentation",
  template = "template"
}

enum Availability {
  required = "required",
  optional = "optional",
  hidden = "hidden"
}

enum MeetingRoomAuthType {
  none = "none",
  invited = "invited",
  accountMember = "accountMember",
  platformMember = "platformMember",
  external = "external"
}

Types

type ApiEventCallback = (
  payload: void 
    | IApiParticipant[] 
    | IApiChatMessage 
    | IApiRemainingTimeUpdate 
    | IMeetingRoomConfig 
    | ICustomMessage 
    | IScreenshareState
  ) => void

type SecondaryVideoPosition = "none" | "left" | "top" | "right" | "bottom";
type SecondaryDisplay = "display" | "hidden";