Using the <whereby-embed> element

This web component allows you to embed a Whereby room in any webpage. It provides a more readable integration, and we’ve also exposed local client events that are sent from the room to the component.

You can try it out like this:
HTML
1
<script type=module src="https://cdn.srv.whereby.com/embed/v1.js"></script>
2
<style>whereby-embed { height: 700px; }</style>
3
<whereby-embed minimal room="https://subdomain.whereby.com/your_room"></whereby-embed>
Copied!
This element changed location in October 2021, use the new URL
https://cdn.srv.whereby.com/embed/v1.js 
to make sure you are on the latest version.
You can also use the hostRoomUrl instead of the roomUrl, if you want to give the user host privileges:
HTML
1
<whereby-embed room="https://subdomain.whereby.com/your_room?roomKey=3fe345a"></whereby-embed>
Copied!
Attributes you can use
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
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
The full list of supported attributes can be found in the URL parameters section.
Usage examples
Basic room embedding:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" />
Copied!
Room embedding with minimal UI:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" minimal />
Copied!
Setting the display name for the current user, starting with audio and video off:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" displayName="John Smith" audio=off video=off />
Copied!
Removing the background to blend with the embedding app and turning off some buttons:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" background=off chat=off people=off leaveButton=off />
Copied!
Use a minimal UI but with the leave and screenshare buttons:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" minimal leaveButton screenshare />
Copied!
Disable the floating self view:
1
<whereby-embed room="https://subdomain.whereby.com/your_room" floatSelf=off />
Copied!
Listening to events
You can listen for events on the <whereby-embed> element. 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 }
​
You can use standard JavaScript to listen to the events. Here's a small demo:
Javascript
1
  const elm = document.querySelector("whereby-embed");
2
  const output = document.querySelector("output");
3
​
4
  function logEvent(event) {
5
    output.innerText += `got event ${JSON.stringify({ type: event.type, detail: event.detail })}\n`;
6
  }
7
  elm.addEventListener("ready", logEvent)
8
  elm.addEventListener("knock", logEvent)
9
  elm.addEventListener("participantupdate", logEvent)
10
  elm.addEventListener("join", logEvent)
11
  elm.addEventListener("leave", logEvent)
12
  elm.addEventListener("participant_join", logEvent)
13
  elm.addEventListener("participant_leave", logEvent)
14
  elm.addEventListener("microphone_toggle", logEvent)
15
  elm.addEventListener("camera_toggle", logEvent)
Copied!
Example output:
1
got event {"type":"participantupdate","detail":{"count":1}}
2
got event {"type":"join","detail":null}
3
got event {"type":"leave","detail":{"removed":false}}
4
got event {"type":"participant_join","detail":{"metadata":"userId"}}
5
got event {"type":"participant_leave","detail":{"metadata":"userId"}}
Copied!
Sending commands
The <whereby-embed> element exposes a set of methods your application can invoke in order to perform actions in the room. Currently, the following methods are available:
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.
Method
Description
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.
Here is a small example showing uses of these methods:
JavaScript
1
const room = document.querySelector("whereby-embed");
2
room.toggleCamera(); // Camera will be turned on if off, and off if on
3
room.toggleMicrophone(); // Microphone will be turned on if off, and off if on
4
room.toggleCamera(true); // Turn camera on
5
room.toggleMicrophone(true); // Turn microphone on
6
room.toggleCamera(false); // Turn camera off
7
room.toggleMicrophone(false); // Turn microphone off
8
​
9
​
Copied!

Using an iframe

Embedding in Squarespace or WordPress

Last modified 2mo ago

Copy link

Contents

Attributes you can use

Listening to events

Sending commands