Edit

IFrame API

Embedding the Jitsi Meet API into your site or app enables you to host and provide secure video meetings with your colleagues, teams, and stakeholders. The Meet API provides a full complement of comprehensive meeting features.

Your Jitsi meetings can be hosted and attended using any device while keeping your data and privacy protected. You can reach your meeting participants anywhere in the world eliminating the need for travel and the associated inconvenience.

The IFrame API enables you to embed Jitsi Meet functionality into your meeting application so you can experience the full functionality of the globally distributed and highly available deployment available with meet.jit.si.

You can also embed and integrate the globally distributed and highly available deployment on the meet.jit.si platform itself.

NOTE

JaaS customers, please make sure you also read this!

Integration

To enable the Jitsi Meet API in your application you must use one of the following JavaScript (JS) Jitsi Meet API library scripts and integrate it into your application:

For self-hosting in your domain:

<script src='https://<your-domain>/external_api.js'></script>

meet.jit.si:

<script src='https://meet.jit.si/external_api.js'></script>

Mobile support

The iframe API works on mobile browsers the same way as it does on desktop browsers.

warning

Currently we are working on better support for Chrome for iOS, expect issues.

Opening meetings in the Jitsi Meet app

In order to open meetings with the Jitsi Meet app you can use our custom URL scheme as follows:

(let's assume the meeting is https://meet.jit.si/test123)

• Android: intent://meet.jit.si/test123#Intent;scheme=org.jitsi.meet;package=org.jitsi.meet;end
• iOS: org.jitsi.meet://meet.jit.si/test123

This works with custom servers too, just replace meet.jit.si with your custom server URL.

Creating the Jitsi Meet API object

After you have integrated the Meet API library, you must then create the Jitsi Meet API object.

The Meet API object takes the following form:

api = new JitsiMeetExternalAPI(domain, options)

The API object constructor uses the following options:

• domain: The domain used to build the conference URL (e.g., meet.jit.si).

• options: The object with properties.

  Optional arguments include:

  • roomName: The name of the room to join.

  • width: The created IFrame width.

    The width argument has the following characteristics:

    • A numerical value indicates the width in pixel units.

    • If a string is specified the format is a number followed by px, em, pt, or %.

  • height: The height for the created IFrame.

    The height argument has the following characteristics:

    • A numerical value indicates the height in pixel units.

    • If a string is specified the format is a number followed by px, em, pt, or %.

  • parentNode: The HTML DOM Element where the IFrame is added as a child.

  • configOverwrite: The JS object with overrides for options defined in the config.js file.

  • interfaceConfigOverwrite: The JS object with overrides for options defined in the interface_config.js file.

  • jwt: The JWT token.

  • onload: The IFrame onload event handler.

  • invitees: Object arrays that contain information about participants invited to a call.

  • devices: Information map about the devices used in a call.

  • userInfo: The JS object that contains information about the participant starting the meeting (e.g., email).

    For example:

const domain = 'meet.jit.si';
const options = {
    roomName: 'JitsiMeetAPIExample',
    width: 700,
    height: 700,
    parentNode: document.querySelector('#meet')
};
const api = new JitsiMeetExternalAPI(domain, options);

You can set the initial media devices for the call using the following:

const domain = 'meet.jit.si';
const options = {
    ...
    devices: {
        audioInput: '<deviceLabel>',
        audioOutput: '<deviceLabel>',
        videoInput: '<deviceLabel>'
    },
    ...
};
const api = new JitsiMeetExternalAPI(domain, options);

You can override options set in the config.js file and the interface_config.js file using the configOverwrite and interfaceConfigOverwrite objects, respectively.

For example:

const options = {
    ...
    configOverwrite: { startWithAudioMuted: true },
    interfaceConfigOverwrite: { DISABLE_DOMINANT_SPEAKER_INDICATOR: true },
    ...
};
const api = new JitsiMeetExternalAPI(domain, options);

To pass a JWT token to Jitsi Meet use the following:

const options = {
   ...
   jwt: '<jwt_token>',
   ...
};
const api = new JitsiMeetExternalAPI(domain, options);

You can set the userInfo (e.g., email, display name) for the call using the following:

var domain = "meet.jit.si";
var options = {
    ...
    userInfo: {
        email: 'email@jitsiexamplemail.com',
        displayName: 'John Doe'
    }
}
var api = new JitsiMeetExternalAPI(domain, options);

Configuring the tile view:

You can configure the maximum number of columns in the tile view by overriding the TILE_VIEW_MAX_COLUMNS property from the interface_config.js file via the interfaceConfigOverwrite object:

const options = {
    ...
    interfaceConfigOverwrite: { TILE_VIEW_MAX_COLUMNS: 2 },
    ...
};
const api = new JitsiMeetExternalAPI(domain, options);

Note: TILE_VIEW_MAX_COLUMNS accepts values from 1 to 5. The default value is 5.

Functions

Use the following API functions to control your embedded Jitsi Meet Conference.

captureLargeVideoScreenshot

Captures a screenshot for the participant in the large video view (on stage).

api.captureLargeVideoScreenshot().then(data => {
    // data is an Object with only one param, dataURL
    // data.dataURL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABQAA..."
});

getAvailableDevices

Retrieves a list of available devices.

api.getAvailableDevices().then(devices => {
    // devices = {
    //     audioInput: [{
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'audioinput'
    //         label: 'label'
    //     },....],
    //     audioOutput: [{
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'audioOutput'
    //         label: 'label'
    //     },....],
    //     videoInput: [{
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'videoInput'
    //         label: 'label'
    //     },....]
    // }
    ...
});

getCurrentDevices

Retrieves a list of currently selected devices.

api.getCurrentDevices().then(devices => {
    // devices = {
    //     audioInput: {
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'videoInput'
    //         label: 'label'
    //     },
    //     audioOutput: {
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'videoInput'
    //         label: 'label'
    //     },
    //     videoInput: {
    //         deviceId: 'ID'
    //         groupId: 'grpID'
    //         kind: 'videoInput'
    //         label: 'label'
    //     }
    // }
    ...
});

getLivestreamUrl

Retrieves an object containing information about livestreamUrl of the current live stream.

api.getLivestreamUrl().then(livestreamData => {
    // livestreamData = {
    //     livestreamUrl: 'livestreamUrl'
    // }
    ...
});

getParticipantsInfo

Returns an array containing participant information such as ID, display name, avatar URL, and email.

api.getParticipantsInfo();

getVideoQuality

Returns the current video quality setting.

api.getVideoQuality();

isDeviceChangeAvailable

Resolves to true if the device change is available and to false if not.

// The accepted deviceType values are - 'output', 'input' or undefined.
api.isDeviceChangeAvailable(deviceType).then(isDeviceChangeAvailable => {
    ...
});

isDeviceListAvailable

Resolves to true if the device list is available and to false if not.

api.isDeviceListAvailable().then(isDeviceListAvailable => {
    ...
});

isMultipleAudioInputSupported

Resolves to true if multiple audio input is supported and to false if not.

api.isMultipleAudioInputSupported().then(isMultipleAudioInputSupported => {
    ...
});

pinParticipant

Selects the participant ID to be the pinned participant in order to always receive video for this participant.

api.pinParticipant(participantId);

resizeLargeVideo

Resizes the large video container per the provided dimensions.

api.resizeLargeVideo(width, height);

setAudioInputDevice

Sets the audio input device to the one with the passed label or ID.

api.setAudioInputDevice(deviceLabel, deviceId);

setAudioOutputDevice

Sets the audio output device to the one with the passed label or ID.

api.setAudioOutputDevice(deviceLabel, deviceId);

setLargeVideoParticipant

Displays the participant with the given participant ID on the large video.

If no participant ID is given, a participant is picked based on the dominant, pinned speaker settings.

api.setLargeVideoParticipant(participantId);

setVideoInputDevice

Sets the video input device to the one with the passed label or ID.

api.setVideoInputDevice(deviceLabel, deviceId);

startRecording

Starts a file recording or streaming session. See the startRecording command for more details.

api.startRecording(options);

stopRecording

Stops an ongoing file recording or streaming session. See the stopRecording command for more details.

api.startRecording(mode);

getNumberOfParticipants

Returns the number of conference participants:

const numberOfParticipants = api.getNumberOfParticipants();

getAvatarURL

Returns a participant's avatar URL:

const avatarURL = api.getAvatarURL(participantId);

getDisplayName

Returns a participant's display name:

const displayName = api.getDisplayName(participantId);

getEmail

Returns a participant's email:

const email = api.getEmail(participantId);

getIFrame

Returns the IFrame HTML element which is used to load the Jitsi Meet conference:

const iframe = api.getIFrame();

isAudioMuted

Returns a Promise which resolves to the current audio muted state:

api.isAudioMuted().then(muted => {
    ...
});

isVideoMuted

Returns a Promise which resolves to the current video muted state:

api.isVideoMuted().then(muted => {
    ...
});

isAudioAvailable

Returns a Promise which resolves to the current audio availability state:

api.isAudioAvailable().then(available => {
    ...
});

isVideoAvailable

Returns a Promise which resolves to the current video availability state:

api.isVideoAvailable().then(available => {
    ...
});

invite

Invite the given array of participants to the meeting:

api.invite([ {...}, {...}, {...} ]).then(() => {
    // success
}).catch(() => {
    // failure
});

NOTE: The invitee format in the array depends on the invite service used in the deployment.

SIP invite objects have the following structure:

{
    type: 'sip',
    address: <string> // the sip address
}

dispose

Removes the embedded Jitsi Meet conference:

api.dispose();

NOTE: Jitsi recommends removing the conference before the page is unloaded.

Commands

You can control the embedded Jitsi Meet conference by calling executeCommand on the JitsiMeetExternalAPI object:

api.executeCommand(command, ...arguments);

The command parameter is a string which contains the command name.

You can also execute multiple commands using the executeCommands method:

api.executeCommands(commands);

The commands parameter is an object with the names of the commands as keys and the arguments for the commands as values:

api.executeCommands({
    displayName: [ 'nickname' ],
    toggleAudio: []
});

The following commands are supported:

displayName

Sets the display name of the local participant.

This command requires one argument to set the new display name.

api.executeCommand('displayName', 'New Nickname');

password

Sets the password for the room.

// set new password for channel
api.addEventListener('participantRoleChanged', function(event) {
    if (event.role === "moderator") {
        api.executeCommand('password', 'The Password');
    }
});
// join a protected channel
api.on('passwordRequired', function ()
{
    api.executeCommand('password', 'The Password');
});

toggleLobby

Toggles the lobby mode on or off.

This command requires the desired lobby mode state as the argument.

api.addEventListener('participantRoleChanged', function (event) {
    if(event.role === 'moderator') {
        api.executeCommand('toggleLobby', true);
    }
});

sendTones

Touch tone playback.

This command requires the selected touch tone dial pads to play as well as the length of and time gap between tone play as the arguments.

api.executeCommand('sendTones', {
    tones: string, // The dial pad touch tones to play. For example, '12345#'.
    duration: number, // Optional. The number of milliseconds each tone should play. The default is 200.
    pause: number // Optional. The number of milliseconds between each tone. The default is 200.
});

subject

Sets the subject of the conference.

This command requires the new subject to be set as the argument.

api.executeCommand('subject', 'New Conference Subject');

toggleAudio

Mutes / unmutes the audio for the local participant.

No arguments are required.

api.executeCommand('toggleAudio');

toggleVideo

Mutes / unmutes the video for the local participant.

No arguments are required.

api.executeCommand('toggleVideo');

toggleFilmStrip

Hide or show the filmstrip.

No arguments are required.

api.executeCommand('toggleFilmStrip');

toggleChat

Hide or show chat messaging.

No arguments are required.

api.executeCommand('toggleChat');

toggleShareScreen

Start or stop screen sharing.

No arguments are required.

api.executeCommand('toggleShareScreen');

toggleTileView

Enter or exit the tile view layout mode.

No arguments are required.

api.executeCommand('toggleTileView');

hangup

Ends the call.

No arguments are required.

api.executeCommand('hangup');

email

Changes the local email address.

This command requires the new email address as the single argument.

api.executeCommand('email', 'example@example.com');

avatarUrl

Changes the local avatar URL.

This command requires the new avatar URL to be set as the single argument.

api.executeCommand('avatarUrl', 'https://avatars0.githubusercontent.com/u/3671647');

sendEndpointTextMessage

Sends a text message to another participant through the data channels.

api.executeCommand('sendEndpointTextMessage', 'receiverParticipantId', 'text');

setLargeVideoParticipant

Displays the participant on the large video display.

The participant ID, if specified, is displayed on the large video. If no argument is passed, the participant to be displayed on the large video is automatically selected based on the dominant/pinned speaker settings.

api.executeCommand('setLargeVideoParticipant', 'abcd1234');

setVideoQuality

Sets the send and receive video resolution.

The resolution height setting is implemented using a single argument.

api.executeCommand('setVideoQuality', 720);

muteEveryone

Mute all meeting participants.

This command can only be executed by the meeting moderator. No arguments are required.

api.executeCommand('muteEveryone');

startRecording

Starts a file recording or streaming session using passed parameters:

• RTMP streaming - Recording mode set to stream with an rtmpStreamKey. The rtmpBroadcastID value is optional.

• YouTube streams - Recording mode set to stream with an youtubeStreamKey. The youtubeBroadcastID value is optional.

• Dropbox recording - Recording mode set to file with a Dropbox OAuth2 token.

Additionally, Dropbox saving should be enabled on the Jitsi meet deploy config you are using.

• File recording - Recording mode set to file.

Optionally, shouldShare should be passed on. No other params are required.

api.executeCommand('startRecording', {
    mode: string //recording mode, either `file` or `stream`.
    dropboxToken: string, //dropbox oauth2 token.
    shouldShare: boolean, //whether the recording should be shared with the participants or not. Only applies to certain jitsi meet deploys.
    rtmpStreamKey: string, //the RTMP stream key.
    rtmpBroadcastID: string, //the RTMP broadcast ID.
    youtubeStreamKey: string, //the youtube stream key.
    youtubeBroadcastID: string //the youtube broacast ID.
});

stopRecording

Stops an ongoing stream or file recording.

The mode in which the recording was started must be specified.

api.executeCommand('stopRecording', 
    mode: string //recording mode to stop, `stream` or `file`
);

initiatePrivateChat

Opens the chat window and sets the participant with the given participant ID as the messages recipient.

api.executeCommand('initiatePrivateChat',
    participantID: string
);

cancelPrivateChat

Removes the private chat participant thus it resets the chat window to group chat.

api.executeCommand('cancelPrivateChat');

getContentSharingParticipants

Returns a promise which resolves with an array of currently sharing participants ID's.

api.executeCommand('getContentSharingParticipants').then(res => {
    //res.sharingParticipantIds = [particId1, particId2, ...]
});

kickParticipant

Kicks the participant with the given participant ID from the meeting.

api.executeCommand('kickParticipant',
    participantID: string
);

overwriteConfig

Overwrite config.js props with values from the config object passed on to the command.

api.executeCommand('overwriteConfig',
    config: Object
);

For example:

api.executeCommand('overwriteConfig',
    {
      toolbarButtons: ['chat']
    }
);

will overwrite the toolbarButtons config value with [chat], resulting in UI only showing the chat button.

setTileView

Enables or disables the tileview mode.

api.executeCommand('setTileView',
    enabled: boolean
);

toggleCamera

Toggles the front/back camera on mobile web.

api.executeCommand('toggleCamera');

toggleCameraMirror

Toggles the mirroring of the local video.

api.executeCommand('toggleCameraMirror');

Events

The JitsiMeetExternalAPI object implements the EventEmitter API for emitting and listening for events.

You can add event listeners to the embedded Jitsi Meet using the addListener method:

api.addListener(event, listener);

If you want to remove a listener you can use the removeListener method:

api.removeListener(event, listener);

The event parameter is a string object with the name of the event.

The listener parameter is a function object with one argument that creates a notification when the event occurs along with related event data.

The following events are currently supported:

cameraError

Provides event notifications about Jitsi Meet having failed to access the meeting camera.

The listener receives an object with the following structure:

{
    type: string, // A constant representing the overall type of the error.
    message: string // Additional information about the error.
}

avatarChanged

Provides event notifications about changes to a participant's avatar.

The listener receives an object with the following structure:

{
    id: string, // the id of the participant that changed his avatar.
    avatarURL: string // the new avatar URL.
}

audioAvailabilityChanged

Provides event notifications about changes to audio availability status.

The listener receives an object with the following structure:

{
    available: boolean // new available status - boolean
}

audioMuteStatusChanged

Provides event notifications about changes to audio mute status.

The listener receives an object with the following structure:

{
    muted: boolean // new muted status - boolean
}

contentSharingParticipantsChanged

Provides real-time list of currently screen sharing participant ID's.

The listener receives an object with the following structure:

{
    data: ["particId1", "particId2", ...]
}

endpointTextMessageReceived

Provides event notifications about a text messages received through data channels.

The listener receives an object with the following structure:

{
    senderInfo: {
        jid: string, // the jid of the sender
        id: string // the participant id of the sender
    },
    eventData: {
        name: string // the name of the datachannel event: `endpoint-text-message`
        text: string // the received text from the sender
    }
}

largeVideoChanged

Provides event notifications about changes in the large video display.

The listener receives an object with the following structure:

{
    id: string // id of the participant that is now on large video in the stage view.
}

log

Provides log event notifications with the log level being one of the values specified in the config.js file in the apiLogLevels property (if not specified the event does not fire).

The listener receives an object with the following structure:

{
    logLevel: string, // A constant representing the log type (info, error, debug, warn).
    args: string // Additional log information.
}

micError

Provides event notifications about Jitsi Meet issues with mic access.

The listener receives an object with the following structure:

{
    type: string, // A constant representing the overall type of the error.
    message: string // Additional information about the error.
}

screenSharingStatusChanged

Provides event notifications about either turning on or off local user screen sharing.

The listener receives an object with the following structure:

{
    on: boolean, //whether screen sharing is on
    details: {

        // From where the screen sharing is capturing, if known. Values which are
        // passed include 'window', 'screen', 'proxy', 'device'. The value undefined
        // will be passed if the source type is unknown or screen share is off.
        sourceType: string|undefined
    }
}

dominantSpeakerChanged

Provides event notifications about dominant speaker changes.

The listener receives an object with the following structure:

{
    id: string //participantId of the new dominant speaker
}

raiseHandUpdated

Provides event notifications about the participant raising/lowering the hand.

The listener will receive an object with the following structure:

{
    id: string,         // participantId of the user who raises/lowers the hand
    handRaised: boolean // whether hand raised or lowered
}

tileViewChanged

Provides event notifications about entrance or exit from the tile view layout mode.

The listener receives an object with the following structure:

{
    enabled: boolean, // whether tile view is not displayed or not
}

chatUpdated

Provides event notifications about chat state being updated.

The listener receives an object with the following structure:

{
    isOpen: boolean, // Whether the chat panel is open or not
    unreadCount: number // The unread messages counter
}

incomingMessage

Provides event notifications about incoming chat messages.

The listener receives an object with the following structure:

{
    from: string, // The id of the user that sent the message
    nick: string, // the nickname of the user that sent the message
    privateMessage: boolean, // whether this is a private or group message
    message: string // the text of the message
}

outgoingMessage

Provides event notifications about outgoing chat messages.

The listener receives an object with the following structure:

{
    message: string, // the text of the message
    privateMessage: boolean // whether this is a private or group message
}

displayNameChange

Provides event notifications about display name changes.

The listener receives an object with the following structure:

{
    id: string, // the id of the participant that changed their display name
    displayname: string // the new display name
}

deviceListChanged

Provides event notifications about device list changes.

The listener receives an object with the following structure:

{
    devices: Object // the new list of available devices.
}

NOTE: The device object has the same format as the getAvailableDevices result format.

emailChange

Provides event notifications about email changes.

The listener receives an object with the following structure:

{
    id: string, // the id of the participant that changed his email
    email: string // the new email
}

feedbackSubmitted

Provides event notifications about conference feedback submissions:

{
    error: string // The error which occurred during submission, if any.
}

filmstripDisplayChanged

Provides event visibility notifications for the filmstrip that is being updated:

{
    visible: boolean // Whether or not the filmstrip is displayed or hidden.
}

participantJoined

Provides event notifications about new participants who join the room.

The listener receives an object with the following structure:

{
    id: string, // the id of the participant
    displayName: string // the display name of the participant
}

participantKickedOut

Provides event notifications about participants being removed from the room.

The listener receives an object with the following structure:

{
    kicked: {
        id: string, // the id of the participant removed from the room
        local: boolean // whether or not the participant is the local particiapnt
    },
    kicker: {
        id: string // the id of the participant who kicked out the other participant
    }
}

participantLeft

Provides event notifications about participants that leave the meeting room.

The listener receives an object with the following structure:

{
    id: string // the id of the participant
}

participantRoleChanged

Provides event notifications that fire when the local user role has changed (e.g., none, moderator, participant).

The listener receives an object with the following structure:

{
    id: string // the id of the participant
    role: string // the new role of the participant
}

passwordRequired

Provides event notifications that fire when participants fail to join a password protected room.

videoConferenceJoined

Provides event notifications that fire when the local user has joined the video conference.

The listener receives an object with the following structure:

{
    roomName: string, // the room name of the conference
    id: string, // the id of the local participant
    displayName: string, // the display name of the local participant
    avatarURL: string // the avatar URL of the local participant
}

videoConferenceLeft

Provides event notifications that fire when the local user has left the video conference.

The listener receives an object with the following structure:

{
    roomName: string // the room name of the conference
}

videoAvailabilityChanged

Provides event notifications about video availability status changes.

The listener receives an object with the following structure:

{
    available: boolean // new available status - boolean
}

videoMuteStatusChanged

Provides event notifications about video mute status changes.

The listener receives an object with the following structure:

{
    muted: boolean // new muted status - boolean
}

videoQualityChanged

Provides event notifications about changes to video quality settings.

The listener receives an object with the following structure:

{
    videoQuality: number // the height of the resolution related to the new video quality setting.
}

readyToClose

Provides event notifications that fire when Jitsi Meet is ready to be closed (i.e., hangup operations are completed).

subjectChange

Provides event notifications regarding the change of subject for a conference.

The listener receives an object with the following structure:

{
    subject: string // the new subject
}

suspendDetected

Provides notifications about detecting suspended events in the host computer.

recordingStatusChanged

Provides event notifications about recording status changes.

The listener receives an object with the following structure:

{
    on: boolean // new recording status - boolean,
    mode: string // recording mode, `stream` or `file`,
    error: string | undefined // error type if recording fails, undefined otherwise
}