JavaScript API Reference

This page provides a reference to the Videola.io JavaScript Embed API, listing the events and functions exposed by the video calling embed.

Global Functions

Videola.Embed.generateRandomCode():String
Returns a random connection code (room name). Useful for creating an ad-hoc call between two or more participants.
Videola.Embed
The constructor of the embed object. Please refer to Embedding the Widget for the list of the constructor parameters.

Embed Object Methods

After you have constructed a Videola.Embed object, you can call its methods to control the various aspects of the embed. This section describes the currently available methods.

Authentication

embed.authorize(tokenHmac:String):Videola.Embed
Supplies the HMAC of a previously provided random token back to the embed as part of the widget authentication scheme. See Embedding the Widget for details.

Call Controls

embed.call(roomName:String, video:Boolean):Videola.Embed
Joins a room. The roomName parameter specifies the room name, and video specifies a video call if true (default) and a voice one if false.
embed.end():Videola.Embed
Ends the current call.
embed.toggleVideo(video:Boolean|String):Videola.Embed
Sets the state of the outgoing video source. The following values are valid for the video parameter:

  • camera – turn on the camera
  • screen – start screen sharing
  • false (Boolean) – turn outgoing video off.
embed.toggleAudio(audio:Boolean):Videola.Embed
Sets the state of the microphone. Pass true in the audio parameter to unmute the mic or pass false to mute it.
embed.toggleRecording(record:Boolean, [layout:String]):Videola.Embed
Starts or stops call recording. Pass true in the record parameter to start call recording or false to stop it. The optional layout parameter lets you specify the layout of the recording as the recording is started. The following layout values are supported:

  • maximized (default) – maximize the currently active speaker
  • tiled – display all participants’ pictures in tiles of approximately the same size.

The recording functionality is only available when the call is ongoing. Check out Call Recording for call recording prerequisites and more information.

embed.toggleRoomLock(locked:Boolean):Videola.Embed
Sets the room’s lock state. Pass true in the locked parameter to lock the room or pass false to unlock it. This functionality is only available when the call is ongoing.
embed.switchCamera():Videola.Embed
Switches the currently active camera to the next available one.

Fullscreen Mode

embed.toggleFullscreen(fullscreen:Boolean):Videola.Embed
Toggles fullscreen mode for the Videola.io embed. Pass true in the fullscreen parameter to switch the embed to fullscreen or false to exit fullscreen mode. Important notes:

  • Switching to fullscreen only works in the call-setup and call states of the embed.
  • Switching to fullscreen does not work in Firefox (the ERROR_FULLSCREEN error is triggered).
  • In the browsers where programmatic switching to fullscreen does work (Chrome, Safari and others), the browser will block switching to fullscreen unless it’s initiated in response to a user gesture on the page, e.g. clicking a button.

Call State

embed.getState():String
Returns the current state of the embed.

Adding Event Handlers

on(event:String, handler:Function):Videola.Embed
Adds a handler function to the specified event. handler is a reference to the function that should get called when the specified event fires. See the Events section below for a description of the different events that the embed might fire.

Method Chaining

Every method of the embed object, except for getters (i.e. methods whose name starts with get) returns the embed object itself. This makes it possible to “chain” API method calls:

Embed Object Events

The API fires events to notify the host application about any changes to the embed. You can subscribe to events with the help of the on method of the Videola.Embed object.

Each event handler is passed a sole event object whose properties may contain additional information about the event. For example, the event object passed by the stateChange event has the state property that contains the new embed state.

Here is a list of the events fired by the API:

ready
This event is fired whenever the embed has finished loading and is ready to interact with the API. Your application should implement a handler for the ready event if you wish to perform certain actions (e.g. start a call) as soon as the embed is ready.
error
This event is fired whenever the Embed API encounters an error. The event object passed to the event handler has the following properties:

  • event.error – the error code. Can be one of the following:
    • ERROR_INTERNAL – internal error
    • ERROR_NO_CONNECTION – lost connection
    • ERROR_BUSY – the call room is locked
    • ERROR_ROOM_LIMIT_REACHED – the room limit of 12 participants has been reached
    • ERROR_INVALID_CREDENTIALS – invalid token signature provided
    • ERROR_FREE_DEMO_ENDED – the 5-minute call limit has been reached (when using the demo client ID)
    • ERROR_MEDIA – error acquiring camera and/or microphone
    • ERROR_FULLSCREEN – error switching the embed to fullscreen mode
    • ERROR_INVALID_CODE – invalid room name to join.
stateChange
This event fires whenever the embed’s state changes. The event object passed to the event handler has the following properties:

  • event.state – the new state of the embed, can be one of the following:
    • ready – idle; provides the additional event.callDuration property that contains the duration of the last call in seconds
    • no-webrtc – displaying a “no WebRTC support” message
    • permissions-request – prompting the user for camera/microphone permissions
    • call-setup – waiting for the other party to join
    • call – call in progress.
requestToSignApiAuthToken
This event is fired whenever the embed requests you to sign a random token as part of the widget authentication scheme. The event object passed to the event handler has the following properties:

  • event.token – the token value to sign.

Please see Embedding the Widget for details.

screenSharingAvailability
This event is fired whenever new information gets available on whether the user’s browser supports outgoing screen sharing. This event may fire multiple times as the widget gathers more information about the screen sharing support. The event object passed to the event handler has the following properties:

  • event.availability – screen sharing availability, can be one of the following:
    • unsupported – the user’s browser doesn’t support outgoing screen sharing
    • available – outgoing screen sharing is available.
streamStateChange
This event is fired whenever the state of the embed’s media stream changes, i.e. the camera or the microphone gets muted or unmuted, or screen sharing is started. The event object passed to the event handler has the following properties:

  • event.audio – the state of the microphone (true for on and false for off)
  • event.video – the state of the outgoing video
  • event.videoSource – the outgoing video source currently being used (possible values: camera for camera and screen for screen sharing).
recordingStateChange
This event is fired whenever the call recording state changes, e.g. one of the call participants begins call recording. The event object passed to the event handler has the following properties:

  • event.us – whether we are currently recording the call (true for recording and false for not recording)
  • event.them – whether one of the other call participants is recording.
recordingFilename
This event is fired shortly after call recording is started locally and reports the filename under which the recording will be uploaded to the S3 bucket or FTP/SFTP. The event object passed to the event handler has the following properties:

  • event.filename – the filename of the recording.
roomLockStateChange
This event is fired whenever the room lock state changes. The event object passed to the event handler has the following properties:

  • event.locked – the current new lock state of the room (true for locked and false for unlocked).
callInit
This event fires whenever a call is initialized.
hangup
This event is fired whenever a call is ended as a result of the user or API action (as opposed to, e.g. remote party disconnecting or lost connection).
fullscreenStateChange
This event is fired whenever the embed enters or exits fullscreen mode. The event object passed to the event handler has the following properties:

  • event.fullscreen – the current fullscreen state of the embed (true for fullscreen and false for not fullscreen).

Revision History

March 1, 2019

  • Initial version.