2017-01-30 09:49:05 +00:00
# Jitsi Meet API
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
You can use the Jitsi Meet API to embed Jitsi Meet in to your application.
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
## Installation
To embed Jitsi Meet in your application you need to add the Jitsi Meet API library:
2017-01-26 01:14:30 +00:00
```javascript
< script src = "https://meet.jit.si/external_api.js" > < / script >
```
2017-03-07 09:39:51 +00:00
## API
2017-07-13 19:23:54 +00:00
### `api = new JitsiMeetExternalAPI(domain, options)`
2017-03-07 09:39:51 +00:00
The next step for embedding Jitsi Meet is to create the Jitsi Meet API object.
Its constructor gets a number of options:
* **domain**: domain used to build the conference URL, "meet.jit.si" for
example.
2017-07-13 19:23:54 +00:00
* **options**: object with properties - the optional arguments:
2017-08-01 05:48:50 +00:00
* **roomName**: (optional) name of the room to join.
2017-07-13 20:24:44 +00:00
* **width**: (optional) width for the iframe which will be created. If a number is specified it's treated as pixel units. If a string is specified the format is number followed by 'px', 'em', 'pt' or '%'.
* **height**: (optional) height for the iframe which will be created. If a number is specified it's treated as pixel units. If a string is specified the format is number followed by 'px', 'em', 'pt' or '%'.
2017-08-01 05:48:50 +00:00
* **parentNode**: (optional) HTML DOM Element where the iframe will be added as a child.
* **configOverwrite**: (optional) JS object with overrides for options defined in [config.js].
2017-07-13 19:23:54 +00:00
* **interfaceConfigOverwrite**: (optional) JS object with overrides for options defined in [interface_config.js].
* **noSsl**: (optional, defaults to true) Boolean indicating if the server should be contacted using HTTP or HTTPS.
* **jwt**: (optional) [JWT ](https://jwt.io/ ) token.
2017-03-07 09:39:51 +00:00
Example:
2017-01-30 09:49:05 +00:00
2017-01-26 01:14:30 +00:00
```javascript
2017-08-01 05:48:50 +00:00
var domain = "meet.jit.si";
2017-07-13 19:23:54 +00:00
var options = {
2017-08-01 05:48:50 +00:00
roomName: "JitsiMeetAPIExample",
2017-07-13 19:23:54 +00:00
width: 700,
height: 700,
2017-08-01 05:48:50 +00:00
parentNode: document.querySelector('#meet')
2017-07-13 19:23:54 +00:00
}
var api = new JitsiMeetExternalAPI(domain, options);
2017-01-26 01:14:30 +00:00
```
2017-03-07 09:39:51 +00:00
You can overwrite options set in [config.js] and [interface_config.js].
2017-04-10 17:59:44 +00:00
For example, to enable the filmstrip-only interface mode, you can use:
2017-01-30 09:49:05 +00:00
2017-01-26 01:14:30 +00:00
```javascript
2017-07-13 19:23:54 +00:00
var options = {
interfaceConfigOverwrite: {filmStripOnly: true}
};
var api = new JitsiMeetExternalAPI(domain, options);
2017-01-26 01:14:30 +00:00
```
2017-03-07 09:39:51 +00:00
You can also pass a jwt token to Jitsi Meet:
2017-03-20 18:39:16 +00:00
```javascript
2017-07-13 19:23:54 +00:00
var options = {
jwt: "< jwt_token > ",
noSsl: false
};
var api = new JitsiMeetExternalAPI(domain, options);
2017-03-20 18:39:16 +00:00
```
2017-03-07 09:39:51 +00:00
### Controlling the embedded Jitsi Meet Conference
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
You can control the embedded Jitsi Meet conference using the `JitsiMeetExternalAPI` object by using `executeCommand` :
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand(command, ...arguments)
```
2017-01-30 09:49:05 +00:00
The `command` parameter is String object with the name of the command. The following commands are currently supported:
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
* **displayName** - Sets the display name of the local participant. This command requires one argument - the new display name to be set.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('displayName', 'New Nickname');
```
2017-01-30 09:49:05 +00:00
* **toggleAudio** - Mutes / unmutes the audio for the local participant. No arguments are required.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('toggleAudio')
```
2017-01-30 09:49:05 +00:00
* **toggleVideo** - Mutes / unmutes the video for the local participant. No arguments are required.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('toggleVideo')
```
2017-01-30 09:49:05 +00:00
2017-04-10 17:59:44 +00:00
* **toggleFilmStrip** - Hides / shows the filmstrip. No arguments are required.
2017-01-30 09:49:05 +00:00
```javascript
api.executeCommand('toggleFilmStrip')
2017-01-26 01:14:30 +00:00
```
2017-01-30 09:49:05 +00:00
* **toggleChat** - Hides / shows the chat. No arguments are required.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('toggleChat')
```
2017-01-30 09:49:05 +00:00
* **toggleContactList** - Hides / shows the contact list. No arguments are required.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('toggleContactList')
```
2017-01-30 09:49:05 +00:00
* **toggleShareScreen** - Starts / stops screen sharing. No arguments are required.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('toggleShareScreen')
```
* **hangup** - Hangups the call. No arguments are required.
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('hangup')
```
2017-01-30 09:49:05 +00:00
* **email** - Changes the local email address. This command requires one argument - the new email address to be set.
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommand('email', 'example@example.com')
```
2017-01-30 09:49:05 +00:00
* **avatarUrl** - Changes the local avatar URL. This command requires one argument - the new avatar URL to be set.
```javascript
api.executeCommand('avatarUrl', 'https://avatars0.githubusercontent.com/u/3671647')
2017-01-26 01:14:30 +00:00
```
2017-01-30 09:49:05 +00:00
You can also execute multiple commands using the `executeCommands` method:
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommands(commands)
```
2017-03-31 16:38:44 +00:00
The `commands` parameter is an object with the names of the commands as keys and the arguments for the commands as values:
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.executeCommands({displayName: ['nickname'], toggleAudio: []});
```
2017-01-30 09:49:05 +00:00
You can add event listeners to the embedded Jitsi Meet using the `addEventListener` method.
2017-04-03 15:48:46 +00:00
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods (`addListener` or `on` ).**
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.addEventListener(event, listener)
```
2017-01-30 09:49:05 +00:00
The `event` parameter is a String object with the name of the event.
The `listener` parameter is a Function object with one argument that will be notified when the event occurs with data related to the event.
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
The following events are currently supported:
* **incomingMessage** - Event notifications about incoming
messages. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"from": from, // JID of the user that sent the message
"nick": nick, // the nickname of the user that sent the message
"message": txt // the text of the message
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
* **outgoingMessage** - Event notifications about outgoing
messages. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"message": txt // the text of the message
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
2017-01-26 01:14:30 +00:00
* **displayNameChanged** - event notifications about display name
2017-01-30 09:49:05 +00:00
changes. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"jid": jid, // the JID of the participant that changed his display name
"displayname": displayName // the new display name
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
* **participantJoined** - event notifications about new participants who join the room. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"jid": jid // the JID of the participant
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
* **participantLeft** - event notifications about participants that leave the room. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"jid": jid // the JID of the participant
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
* **videoConferenceJoined** - event notifications fired when the local user has joined the video conference. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"roomName": room // the room name of the conference
2017-01-26 01:14:30 +00:00
}
```
2017-01-30 09:49:05 +00:00
* **videoConferenceLeft** - event notifications fired when the local user has left the video conference. The listener will receive an object with the following structure:
```javascript
2017-01-26 01:14:30 +00:00
{
2017-01-30 09:49:05 +00:00
"roomName": room // the room name of the conference
2017-01-26 01:14:30 +00:00
}
```
* **readyToClose** - event notification fired when Jitsi Meet is ready to be closed (hangup operations are completed).
2017-01-30 09:49:05 +00:00
You can also add multiple event listeners by using `addEventListeners` .
2017-01-26 01:14:30 +00:00
This method requires one argument of type Object. The object argument must
2017-01-30 09:49:05 +00:00
have the names of the events as keys and the listeners of the events as values.
2017-04-03 15:48:46 +00:00
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods.**
2017-01-26 01:14:30 +00:00
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
function incomingMessageListener(object)
{
2017-01-30 09:49:05 +00:00
// ...
2017-01-26 01:14:30 +00:00
}
function outgoingMessageListener(object)
{
2017-01-30 09:49:05 +00:00
// ...
2017-01-26 01:14:30 +00:00
}
api.addEventListeners({
incomingMessage: incomingMessageListener,
outgoingMessage: outgoingMessageListener})
```
2017-01-30 09:49:05 +00:00
If you want to remove a listener you can use `removeEventListener` method with argument the name of the event.
2017-04-03 15:48:46 +00:00
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods( `removeListener` ).**
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.removeEventListener("incomingMessage");
```
2017-01-30 09:49:05 +00:00
If you want to remove more than one event you can use `removeEventListeners` method with an Array with the names of the events as an argument.
2017-04-03 15:48:46 +00:00
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods.**
2017-01-30 09:49:05 +00:00
```javascript
2017-01-26 01:14:30 +00:00
api.removeEventListeners(["incomingMessage", "outgoingMessageListener"]);
```
2017-01-30 09:49:05 +00:00
You can get the number of participants in the conference with the following API function:
```javascript
2017-01-26 01:14:30 +00:00
var numberOfParticipants = api.getNumberOfParticipants();
```
2017-07-13 18:10:32 +00:00
You can get the iframe HTML element where Jitsi Meet is loaded with the following API function:
```javascript
var iframe = api.getIFrame();
```
2017-01-30 09:49:05 +00:00
You can remove the embedded Jitsi Meet Conference with the following API function:
```javascript
2017-01-26 01:14:30 +00:00
api.dispose()
```
2017-01-30 09:49:05 +00:00
NOTE: It's a good practice to remove the conference before the page is unloaded.
[config.js]: https://github.com/jitsi/jitsi-meet/blob/master/config.js
[interface_config.js]: https://github.com/jitsi/jitsi-meet/blob/master/interface_config.js
2017-03-31 16:38:44 +00:00
[EventEmitter]: https://nodejs.org/api/events.html