Web Component Reference

Our web component allows you to embed Whereby's pre-built UI on any webpage. It provides a simple readable integration and exposes local client events and commands between our platform and yours.

Installation

When using React or a bundler like Webpack, Rollup, Parcel, etc

npm install @whereby.com/browser-sdk

import "@whereby.com/browser-sdk/embed"

HTML

<whereby-embed room="https://subdomain.whereby.com/your_room?roomKey=3fe345a"></whereby-embed>

You can use a hostRoomUrl instead of the roomUrl, if you want to give the user host privileges

JSX

If you aren't using a bundler or a library containing a bundler you can access the component code directly from our CDN using a simple Script tag in your site

Attributes of the component

The web component has a variety of attributes available to customize the meeting experience for your users. It’s possible for each participant in a meeting to have different attribute combinations.

Attribute	Description
aec=off	Turn off acoustic echo cancellation on audio, useful in situations where higher quality audio is important like in music lessons. AEC must be on in order to use the in room "Noise Reduction" feature.
agc=off	Turn off automatic gain control (or volume level) on audio. AGC must be on in order to use the in room "Noise Reduction" feature.
audio=off	Participant joins the room with microphone turned off.
audioDenoiser=on audioDenoiser=off	Enables/Disables the noise cancellation feature. Can increase CPU load, particularly for older/slower devices.
autoHideSelfView	Automatically hide the self view in the bottom right. Floating the self view to the bottom right is required in order to hide the self view. Must be used with floatSelf for this feature to work.
autoSpotlight	Automatically spotlight the local participant on room join. Only works when the participant joining has host privileges.
avatarUrl=<url>	Set the profile avatar of participant. Images must be a square .png or .jpg, maximum of 64pxx64px The image URL must be listed in the allowed domains section of the dashboard. The image URL must be https and cannot contain query params.
background=off	Hide the room background.
bottomToolbar=on bottomToolbar=off	Show/hide the entire bottom toolbar.
breakout=on breakout=off	Show/hide the breakout room feature for the meeting host.
callQualityMonitoring=on callQualityMonitoring=off	Show/hide the meeting diagnostics button, sidebar, and indicators. The rooms top toolbar is required to use the meeting diagnostics feature.
cameraAccess=on cameraAccess=off	Camera permissions are not requested or used at all. On by default.
cameraEffect=<effect>	Set default camera effect to be used. Still user changeable. Possible values: slight-blur, blur, image-cabin, image-concrete, image-brick, image-sunrise, image-day, image-night
chat=on chat=off	Show/hide the chat button.
chatDownload=on chatDownload=off	Allows you to download the chat transcript from a session once it's finished. This will only enable the chat download functionality for the user that has this parameter included in their URL.
displayName=<name>	Set display name of participant. Supports any characters except code characters $!<>:; and can be up to 100 characters long. Strings not in this format will be rejected and the user will be prompted to enter a different display name instead.
externalId=<id>	A custom identifier for the participant. Gets saved in Insights data. Supports alphanumeric characters (A-Za-z0-9-_) and can be up to 36 characters long. Strings not in this format will be rejected and return an error. We recommend the UUID v4 format.
floatSelf	Float the self view to the bottom right.
groups=<group-names> e.g. Orange,Banana,Coconut	Predefine up to 20 groups for the breakout groups function.
highlightActiveSpeaker=on highlightActiveSpeaker=off	Show/hide active speaker highlighting in real-time.
lang=<code>	Set the room UI language. Possible values: Czech cs, Chinese (Traditional) zh-hant, Danish da, Dutch nl, English en, French fr, German de, Greek el, Hindi hi, Hungarian hu, Italian it, Japanese jp, Norwegian nb, Portuguese pt, Polish pl, Spanish es, Swedish sv, or Ukrainian uk
leaveButton=on leaveButton=off	Show/hide the leave button.
localization=on localization=off	Show/hide the language picker. Hiding the localization options means the user will not be able to change their language preference.
locking=off	Hide the room lock button.
logo=off	Hide the logo in the room header.
lowData=on lowData=off	Use a lower resolution by default.
metadata=<string>	Gets passed on to the corresponding webhooks.
minimal	Applies a minimal UI. Turns off all controls except for cam and mic. Hidden items: top bar, chat, screensharing, leave button, and Whereby’s default branding. Shown items: Video, audio, and people buttons.
moreButton=off	Hide the more [...] button.
participantCount=off	Hide the participant counter.
people=off	Hide the people button.
pipButton=off	Hide the Picture in Picture button.
precallCeremony=on precallCeremony=off	Determines if users see the pre-call device and connectivity test. This feature is a subset of the Pre-call review. This means in order for the pre-call tests to appear, pre-call cannot be turned off.
precallCeremonyCanSkip=on	Adds functionality for participants to skip the connectivity test. This feature is a subset of the Pre-call review. This means in order for the pre-call tests to appear, pre-call cannot be turned off.
precallPermissionHelpLink=<url>	Specify custom help link in pre-call review step pointing users to additional support pages.
precallReview=on precallReview=off	Determines if users see the pre-call review step.
roomIntegrations=on	Enables YouTube and Miro integrations in the meeting. It is recommended you do testing to verify these integrations behave as expected before releasing to your users.
screenshare=on screenshare=off	Show/hide the screenshare button.
settingsButton=off	Hide the settings button.
skipMediaPermissionPrompt	Skip the 'request permissions' screen and immediately trigger the browser’s camera/microphone prompt
subgridLabels=on subgridLabels=off	Enable name labels for participants in the subgrid.
timer=on timer=off	Show/hide the meeting timer.
toolbarDarkText	Sets button icon labels color to black.
toolbarText=on toolbarText=off	Removes text from labels in the room toolbar.
topToolbar=on topToolbar=off	Show/hide the entire top toolbar.
video=off	Participant joins the room with camera turned off.
virtualBackgroundUrl=<url>	Specify custom virtual background which should be applied to the local participant. The image must be provided in 1280x720 resolution in either image/jpeg or image/png format. In addition, the image should be retrievable using CORS.

There are additional room customizations and options that can be found in the URL parameters section. These options must be added as parameters on the room source URL, and are not currently supported as attributes directly on the component.

Usage examples

Room w/ multiple customizations

<whereby-embed room="https://subdomain.whereby.com/your_room" displayName="John Smith" audio=off video=off background=off chat=off />

Basic room embed

Room w/ minimal UI

Listening to events

You can listen for events on the <whereby-embed> component. The following events are supported:

Event type	Description	Properties (from "detail")
ready	Basic dependencies have loaded and the room is ready to be used	–
grant_device_permission	The local user grants permission to camera and microphone in the pre-call screen	{ granted: Boolean }
deny_device_permission	The local user denies permission to camera and microphone in the pre-call screen	{ denied: Boolean }
precall_check_completed	The local user completed the presented pre-call check steps. Possible values for all status properties: passed | failed.	{ status: String, steps: { camera: { status: String; }, speaker: { status: String; }, microphone: { status: String; }, bandwidth: { status: String; }, } }
precall_check_skipped	The local user skipped the presented pre-call check steps	-
knock	The local user knocks to get into the room	–
cancel_knock	The local user cancels the knock	-
join	The local user joins	–
leave	The local user leaves	{ removed: Boolean }
meeting_end	A host has ended the meeting via "end meeting for all"	–
participantupdate	A new participant join/leave	{ count: Number }
participant_join	A new participant joins the room	{ participant: { metadata: String } }
participant_leave	A participant leaves the room	{ participant: { metadata: String } }
microphone_toggle	The local user toggles the microphone	{ enabled: Boolean }
camera_toggle	The local user toggles the camera	{ enabled: Boolean }
chat_toggle	The local user toggles the chat	{ open: Boolean }
people_toggle	The local user toggles the people pane	{ open: Boolean }
pip_toggle	The local user toggles Picture-in-Picture mode	{ open: Boolean }
screenshare_toggle	The local user toggles the screenshare	{ enabled: Boolean }
streaming_status_change	Streaming status changes. Possible values: requested | starting | streaming | stopping | stopped	{ status: String }
recording_status_change	Recording status changes. Possible values: starting | started | stopped	{ status: String }
transcription_status_change	Transcription status changes. Possible values: starting | started | stopped	{ status: String }
connection_status_change	User connection status changes. Possible values: stable | unstable	{ status: String }

You can use standard JavaScript to listen to the events. Here's an example:

  const elm = document.querySelector("whereby-embed");
  let output = "";

  function logEvent(event) {
    output = `got event ${JSON.stringify({ type: event.type, detail: event.detail })}\n`;
    console.log(output)
  }
  elm.addEventListener("ready", logEvent)
  elm.addEventListener("precall_check_skipped", logEvent)
  elm.addEventListener("precall_check_completed", logEvent)
  elm.addEventListener("knock", logEvent)
  elm.addEventListener("participantupdate", logEvent)
  elm.addEventListener("join", logEvent)
  elm.addEventListener("leave", logEvent)
  elm.addEventListener("participant_join", logEvent)
  elm.addEventListener("participant_leave", logEvent)
  elm.addEventListener("microphone_toggle", logEvent)
  elm.addEventListener("camera_toggle", logEvent)
  elm.addEventListener("chat_toggle", logEvent)
  elm.addEventListener("people_toggle", logEvent)
  elm.addEventListener("pip_toggle", logEvent)
  elm.addEventListener("deny_device_permission", logEvent)
  elm.addEventListener("screenshare_toggle", logEvent)
  elm.addEventListener("streaming_status_change", logEvent)
  elm.addEventListener("connection_status_change", logEvent)

Example output:

got event {"type":"ready","detail":null}
got event {"type":"deny_device_permission","detail":{"denied":false}}
got event {"type":"precall_check_completed","detail":{"status":"failed",steps: {"camera":"passed","speaker":"failed","microphone":"failed","bandwidth":"passed"}}}
got event {"type":"join","detail":null}
got event {"type":"participant_join","detail":{"metadata":"userId"}}
got event {"type":"participantupdate","detail":{"count":2}}
got event {"type":"participant_leave","detail":{"metadata":"userId"}}
got event {"type":"participantupdate","detail":{"count":1}}
got event {"type":"streaming_status_change","detail":{"status":"starting"}}
got event {"type":"connection_status_change","detail":{"status":"unstable"}}
got event {"type":"leave","detail":{"removed":false}}

Sending commands

For this feature to work, you must add the origin of your application to the "Allowed domains" section in your Whereby account. If not present, the following methods will not do anything.

The <whereby-embed> component exposes a set of methods your application can invoke to perform actions in the room. Currently, the following methods are available:

Method	Description
endMeeting()	End meeting for all on behalf of the local user, who needs to be a host in the room.
knock()	Knock on a locker room, on behalf of the local user.
cancelKnock()	Cancel the knock, on behalf of the local user.
leaveRoom()	Allows local user to leave the room.
startRecording()	Start cloud recording on behalf of the local user, who needs to be a host in the room.
stopRecording()	Stop cloud recording on behalf of the local user, who needs to be a host in the room.
startStreaming()	Start streaming on behalf of the local user, who needs to be a host in the room.
stopStreaming()	Stop streaming on behalf of the local user, who needs to be a host in the room.
startLiveTranscription()	Start live transcription on behalf of the local user, who needs to be a host in the room.
stopLiveTranscription()	Stop live transcription on behalf of the local user, who needs to be a host in the room.
toggleCamera([true | false])	Toggle the local user's camera on or off. Without any arguments, it toggles depending on current state.
toggleMicrophone([true | false])	Toggle the local user's microphone on or off. Without any arguments, it toggles depending on current state.
toggleScreenshare([true | false])	Toggle the local user's screenshare on or off. Without any arguments, it toggles depending on current state.
toggleChat([true | false])	Toggle the local user's chat open or closed. Without any arguments, it toggles depending on current state.

Here is a small example showing uses of these methods:

const room = document.querySelector("whereby-embed");
room.startRecording(); // Start cloud recording
room.stopRecording(); // Stop cloud recording
room.startStreaming(); // Start streaming
room.stopStreaming(); // Stop streaming
room.startLiveTranscription(); // Start live transcription
room.stopLiveTranscription(); // Stop live transcription
room.toggleCamera(); // Camera will be turned on if off, and off if on
room.toggleMicrophone(); // Microphone will be turned on if off, and off if on
room.toggleScreenshare(); // Screenshare will be turned on if off, and off if on
room.toggleChat(); // Chat will be opened if on, and closed if off
room.toggleCamera(true); // Turn camera on
room.toggleMicrophone(true); // Turn microphone on
room.toggleScreenshare(true); // Turn screenshare on
room.toggleCamera(false); // Turn camera off
room.toggleMicrophone(false); // Turn microphone off
room.toggleScreenshare(false); // Turn screenshare off