Skip to main content

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
}

breakoutRoomsUpdated​

Provides notifications about breakout rooms changes.

The listener receives an object with the following structure:

{
    [roomId]: {
        id: string,
        jid: string,
        name: string,
        isMainRoom: true | undefined,
        participants: {
            [participantJid]: {
                displayName: string,
                jid: string,
                role: string
            }
        }
    },
    ...
}

browserSupport​

Provides event notifications about the current browser support.

The listener receives an object with the following structure:

{
    supported: 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", ...]
}

customNotificationActionTriggered​

Callback that triggers for custom actions defined for the showNotification command

The listener receives an object with the following structure:

{
    data: {
        id: string // uuid of the triggered action
    }
}

dataChannelOpened​

Indicates the data channel is open and thus messages can be sent over it.

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
    }
}

nonParticipantMessageReceived​

Provides event notifications about a messages sent by a non-participant, e.g. a custom prosody message.

The listener receives an object with the following structure:

{
        id: string, // the id of the message, may be null
        message: string // the message received
}

faceLandmarkDetected​

Provides event notifications when a face landmark is detected

The listener receives an object with the following structure:

{
    faceBox: {
        left: number, // face bounding box distance as percentage from the left video edge
        right: number // face bounding box distance as percentage from the right video edge
        width: number // face bounding box width as percentage of the total video width
    }, // this might be undefined if config.faceLandmarks.faceCenteringThreshold is not passed
    faceExpression: string // check https://github.com/jitsi/jitsi-meet/blob/master/react/features/face-landmarks/constants.js#L3 for available values
}

errorOccurred​

Provides event notifications about an error which has occurred.

The listener receives an object with the following structure:

{
    details: Object?, // additional error details
    message: string?, // the error message
    name: string, // the coded name of the error
    type: string, // error type/source, one of : 'CONFIG', 'CONNECTION', 'CONFERENCE'
    isFatal: boolean // whether this is a fatal error which triggered a reconnect overlay or not
}

knockingParticipant​

Provides event notifications about a knocking participant in the lobby.

The listener receives an object with the following structure:

{
    participant: {
        // the id and name of the participant that is currently knocking in the lobby
        id: string,
        name: string
    }
}

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: number  // 0 when hand is lowered and the hand raised timestamp when raised.
}

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
    stamp: string // the message timestamp as string (ISO-8601)
}

mouseEnter​

Provides event notifications when mouse enters the iframe. The listener receives an object with the following structure based on MouseEvent:

{
    event: {
        clientX,
        clientY,
        movementX,
        movementY,
        offsetX,
        offsetY,
        pageX,
        pageY,
        x,
        y,
        screenX,
        screenY
    }
}

mouseLeave​

Provides event notifications when mouse leaves the iframe. The listener receives an object with the following structure based on MouseEvent:

{
    event: {
        clientX,
        clientY,
        movementX,
        movementY,
        offsetX,
        offsetY,
        pageX,
        pageY,
        x,
        y,
        screenX,
        screenY
    }
}

mouseMove​

Provides event notifications when mouse moves inside the iframe. Tis event is triggered on an interval which can be configured by overriding the config.js mouseMoveCallbackInterval property.

The listener receives an object with the following structure based on MouseEvent:

{
    event: {
        clientX,
        clientY,
        movementX,
        movementY,
        offsetX,
        offsetY,
        pageX,
        pageY,
        x,
        y,
        screenX,
        screenY
    }
}

participantMenuButtonClick​

Provides event notifications about a participant context menu button being clicked.

The listener receives an object with the following structure:

{
    key: string, // the pressed button's key. The key is as defined in `toolbarButtons` config,
    participantId: string, // the id of the participant for which the button was clicked,
    preventExecution: boolean // whether the execution of the button click was prevented or not
}

toolbarButtonClicked​

Provides event notifications about a toolbar button being clicked and whether the click routine was executed or not. To enable this notification you need to add the button to buttonsWithNotifyClick config.

The listener receives an object with the following structure:

{
    key: string, // the pressed button's key. The key is as defined in `toolbarButtons` config,
    preventExecution: boolean // whether the click routine execution was prevented or not.
}

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.
}

fileDeleted​

Provides event notifications when a file is deleted from the meeting.

The listener receives an object with the following structure:

{
    fileId: string // The ID of the deleted file
}

fileUploaded​

Provides event notifications when a file is uploaded to the meeting.

The listener receives an object with the following structure:

{
    file: {
      authorParticipantId: string,   // ID of participant who uploaded the file
      authorParticipantJid: string,  // Full JID of participant who uploaded the file
      authorParticipantName: string, // Display name of participant who uploaded the file
      conferenceFullName: string,    // Full conference JID
      fileId: string,                // Unique ID of the file
      fileName: string,              // Name of the file
      fileSize: number,              // Size of the file in bytes
      fileType: string,              // File extension/type
      timestamp: number              // Upload timestamp in milliseconds
    }
}

filmstripDisplayChanged​

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

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

toolbarVisibilityChanged​

Provides event notifications when the in-page Jitsi Meet toolbar (toolbox) is shown or hidden.

The listener receives an object with the following structure:

{
    visible: boolean // Whether the toolbar is currently visible.
}

moderationStatusChanged​

Provides event notifications about changes to moderation status.

{
    mediaType: string, // The media type for which moderation changed.
    enabled: boolean // Whether or not moderation changed to enabled.
}

moderationParticipantApproved​

Provides event notifications about participants approvals for moderation.

{
    id: string, // The ID of the participant that got approved.
    mediaType: string // The media type for which the participant was approved.
}

moderationParticipantRejected​

Provides event notifications about participants rejections for moderation.

{
    id: string, // The ID of the participant that got rejected.
    mediaType: string // The media type for which the participant was rejected.
}

notificationTriggered​

Provides event notifications when an application notification occurs.

{
    title: string, // The notification title.
    description: string // The notification description.
}

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
    userContext: {
        id: string // the JWT id 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
}

participantsPaneToggled​

Provides event notifications that fire when the participants pane status changes.

The listener receives an object with the following structure:

{
    open: boolean // whether the pane is open or not
}

participantMuted​

Provides event notifications about participant mute state changes.

The listener receives an object with the following structure:

{
    participantId: string, // the id of the participant whose mute state changed
    isMuted: boolean, // whether the participant is now muted
    mediaType: string // the media type: 'audio' or 'video'
}

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
    breakoutRoom: boolean, // whether the current room is a breakout room
    visitor: boolean // whether the current user is a visitor
}

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
}

conferenceCreatedTimestamp​

Provides notification of the start time of the video conference.

The listener receives an object with the following structure:

{
    timestamp: timestamp // time the conference started
}

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).

recordingLinkAvailable​

Provides event notifications about recording link becoming available.

The listener receives an object with the following structure:

{
    link: string, // the recording link
    ttl: number // the time to live of the recording link
}

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, `local`, `stream` or `file`,
    error: string | undefined // error type if recording fails, undefined otherwise
    transcription: boolean // whether a transcription is active or not
}

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.

peerConnectionFailure​

Notify the external application that a PeerConnection lost connectivity. This event is fired only if a PC failed but connectivity to the rtcstats server is still maintained signaling that there is a problem establishing a link between the app and the JVB server or the remote peer in case of P2P. Will only fire if rtcstats is enabled.

{
    // Type of PC, Peer2Peer or JVB connection.
    isP2P: boolean,

    // Was this connection previously connected. If it was it could mean
    // that connectivity was disrupted, if not it most likely means that the app could not reach
    // the JVB server, or the other peer in case of P2P.
    wasConnected: boolean
}

transcribingStatusChanged​

Provides event notifications about status changes in the transcribing process.

The listener receives an object with the following structure:

{
    on: boolean,
}

transcriptionChunkReceived​

Provides event notifications about new transcription chunks being available.

The listener receives an object with the following structure:

{
    // Transcription language
    language: string,

    // ID for this chunk.
    messageID: string,

    // participant info
    participant: {
        avatarUrl: string,
        id: string
        name: string,
    },

    // If the transcription is final, the text will be here.
    final: string,

    // If the transcription is not final but has high accuracy the text will be here.
    stable: string,

    // If the transcription is not final but has low accuracy the text will be here.
    unstable: string,
}

whiteboardStatusChanged​

Provides event notifications about changes to the whiteboard.

The listener receives an object with the following structure:

{
    status: string // new whiteboard status
}

p2pStatusChanged​

Provides event notifications about changes to the connection type.

The listener receives an object with the following structure:

{
    isP2p: boolean|null // whether the new connection type is P2P
}

audioOnlyChanged​

Provides event notifications about changes to the audio only mode status.

The listener receives an object with the following structure:

{
    audioOnlyChanged: boolean // whether the audio only is enabled or disabled.
}