Links

Web Component Reference

Our web component allows you to embed a Whereby room in 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
JSX
<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​
const MyComponent = ({ roomUrl }) => {
return <whereby-embed room={roomUrl} />
}
​
export default MyComponent
You can use a hostRoomUrl instead of the roomUrl, if you want to give the user host privileges​
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

Attribute
Value
Description
room
A room URL
The full URL of the room you want to embed (required)
minimal
Nothing (on) or "off"
Apply minimal UI for embed scenarios
displayName
Any string
Set displayname of participant
externalId
Up to 36 alphanumeric characters (details)
Custom identifier for the participant.
audio=off
"off"
Enter meeting with audio off
video=off
"off"
Enter meeting with video off
background=off
"off"
Render without background to let embedding app render its own
chat
Nothing (on) or "off"
Enable/disable chat
people
"off"
Disable the participant list
leaveButton
Nothing (on) or "off"
Enable/disable the leave button
screenshare
Nothing (on) or "off"
Enable/disable screenshare
subgridLabels
Nothing (off) or "on"
Enable/disable name labels in the subgrid
floatSelf
Nothing (on) or "off"
Float the self view to the bottom right
lowData
Nothing (on) or "off"
Use a lower resolution by default
cameraAccess
Nothing (on) or "off"
Disable camera access for the local participant, allowing for only audio input
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

Basic room embed
Room w/ minimal UI
Room w/ multiple customizations
<whereby-embed room="https://subdomain.whereby.com/your_room" />
<whereby-embed room="https://subdomain.whereby.com/your_room" minimal />
<whereby-embed room="https://subdomain.whereby.com/your_room" displayName="John Smith" audio=off video=off background=off chat=off />
​

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
–
knock
The local user knocks to get into the room
–
participantupdate
A new participant join/leave
{ count: Number }
join
The local user joins
–
leave
The local user leaves
{ removed: Boolean }
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 }
deny_device_permission
The local user denies permission to camera and microphone in the pre-call screen
{ denied: 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 }
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("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":"participantupdate","detail":{"count":1}}
got event {"type":"join","detail":null}
got event {"type":"leave","detail":{"removed":false}}
got event {"type":"participant_join","detail":{"metadata":"userId"}}
got event {"type":"participant_leave","detail":{"metadata":"userId"}}
got event {"type":"deny_device_permission","detail":{"denied":false}}
got event {"type":"streaming_status_change","detail":{"status":"starting"}}
got event {"type":"connection_status_change","detail":{"status":"stable"}}

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
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.
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.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
Last modified 24d ago