JavaScript API Reference

This is legacy documentation. We are no longer onboarding new Gruveo for Developers customers.

This page provides a reference to Gruveo's JavaScript Embed API, listing the events and functions exposed by the Gruveo embed.

Global Functions

Gruveo.Embed.generateRandomCode():String
Returns a random connection code (room name). Useful for generating a random room name for establishing a call between two or more participants.
Gruveo.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 Gruveo.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):Gruveo.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(code:String, video:Boolean, [record:Boolean], [layout:String]):Gruveo.Embed
Starts a call on code, which can be a room name or a Gruveo handle. The video parameter specifies a video call if true and a voice one if false. Pass true in the optional record parameter to automatically start call recording once the call is established. The optional layout parameter lets you specify the layout of the recording. 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.
embed.end():Gruveo.Embed
Ends the current call.
embed.toggleVideo(video:Boolean|String):Gruveo.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):Gruveo.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]):Gruveo.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):Gruveo.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():Gruveo.Embed
Switches the currently active camera to the next available one.
embed.getSnapshot(includeSelf:Boolean):Gruveo.Embed
Captures a snapshot of the participants' videos. After being called, this method emits a snapshot event (see below) with the snapshot images. Pass true in the includeSelf parameter to also include a snapshot of the local video.

Fullscreen Mode

embed.toggleFullscreen(fullscreen:Boolean):Gruveo.Embed
Toggles fullscreen mode for the Gruveo 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):Gruveo.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 Gruveo.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_HANDLE_UNREACHABLE - the callee is unreachable
    • ERROR_HANDLE_NONEXIST - the Gruveo handle doesn’t exist
    • ERROR_HANDLE_BUSY - the callee is busy with another call
    • 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 or handle to call.
  • event.details - error details, available only for the ERROR_MEDIA error.
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 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 Gruveo 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
    • extension-pending - the Chrome screen sharing extension is being initialized
    • extension-outdated - the Chrome screen sharing extension need to be updated to the latest version
    • extension-missing - the Chrome screen sharing extension is missing
    • extension-unknown-state - unknown state of the Chrome screen sharing extension
    • 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.
busy
Fires whenever a call room is locked or a Gruveo handle is busy.
hangup
This event is fired whenever a call as 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).
snapshot
This event is fired in response to calling the embed.getSnapshot() method (see above). The event object passed to the event handler has the following properties:

  • event.images - array of the participants' video snapshots. If true was passed for includeSelf when calling embed.getSnapshot(), then the first element in the array will be the local video snapshot. If a particular participant is audio-only, then the corresponding array item will be undefined.

Revision History

October 1, 2021

  • Added the new embed.getSnapshot() method and the corresponding snapshot event.

June 3, 2021

  • Added the new optional record and layout parameters to the embed.call() method.
  • Added event.details for the ERROR_MEDIA error.

August 3, 2018

  • Added the new optional layout parameter to the embed.toggleRecording() method.

July 30, 2018

  • Documented fullscreen support. See the description of the embed.toggleFullscreen() method, the fullscreenStateChange event and the ERROR_FULLSCREEN error.

June 4, 2018

  • Documented screen sharing support. See the description of the embed.toggleVideo() method as well as the screenSharingAvailability and streamStateChange events.

May 10, 2018

  • Removed the no longer used plugin-needed state in the error event.

November 27, 2017

  • Documented the error codes that can be passed in the error event.

November 3, 2017

  • Added the new error event.

September 27, 2017

  • Added the new recordingFilename event.

July 31, 2017

  • Added the new toggleRecording() method.
  • Added the new recordingStateChange event.

July 25, 2017

  • Added the new toggleRoomLock() and switchCamera() methods.
  • Added the new roomLock event.
  • Added the new Gruveo.Embed.generateRandomCode() global function.

July 21, 2016

  • The new clientid parameter has been added to the API signing schema.

April 19, 2016

  • The new callInit, busy and hangup API events have been added to allow for better tracking of user interaction with the Gruveo embed.

February 24, 2016

  • The new toggleVideo() and toggleAudio() API methods allow for muting or unmuting the camera and the microphone, respectively.
  • The new streamStateChange event is fired whenever the camera and/or the microphone gets muted or unmuted.

December 22, 2015

  • The Requirements section has been updated to note that Gruveo will not work if embedded in a non-secure HTTP page.

October 19, 2015

  • Initial version.