| description |
|---|
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. |
When using React or a bundler like Webpack, Rollup, Parcel, etc
npm install @whereby.com/browser-sdkimport "@whereby.com/browser-sdk/embed"{% tabs %} {% tab title="HTML" %} {% code overflow="wrap" %}
<whereby-embed room="https://subdomain.whereby.com/your_room?roomKey=3fe345a"></whereby-embed>{% endcode %}
You can use a hostRoomUrl instead of the roomUrl, if you want to give the user host privileges
{% endtab %}
{% tab title="JSX" %}
const MyComponent = ({ roomUrl }) => {
return <whereby-embed room={roomUrl} />
}
export default MyComponentYou can use a hostRoomUrl instead of the roomUrl, if you want to give the user host privileges
{% endtab %}
{% endtabs %}
{% hint style="info" %} 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 {% endhint %}
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 | Value | Description |
|---|---|---|
aec | Nothing (on) or "off" | Turn off acoustic echo cancellation on audio |
agc | Nothing (on) or "off" | Turn off acoustic echo cancellation on audio |
audio | "off" | Enter meeting with audio off |
audioDenoiser | Nothing (on) or "off" | Enables/Disables the noise cancelation feature |
autoHideSelfView | Nothing (off) or "on" | Automatically hide the self view in the bottom right |
autoSpotlight | Nothing (on) or "off" | Automatically spotlight the local "host" on room join |
avatarUrl | Image URL - Must be HTTPS and cannot contain query params | Set the avatar picture of the participant. The image must be a .png or .jpeg, and a square maximum of 64x64. |
background | "off" | Render without background to let embedding app render its own |
bottomToolbar | "off" | Hide the entire bottom tool bar. Useful if creating buttons using commands |
breakout | Nothing (on) or "off" | Show/hide the Breakout Groups feature for the meeting host. |
cameraAccess | Nothing (on) or "off" | Disable camera access for the local participant, allowing for only audio input |
cameraEffect | slight-blur, blur, image-cabin, image-concrete, image-brick, image-sunrise, image-day, image-night | Set the default camera effect to be used. |
chat | Nothing (on) or "off" | Enable/disable chat |
callQualityMonitoring | Nothing(off) or "on" | Enable/disable Whereby's call quality monitoring interface |
displayName | 100 character string - Excluding $!<>:; | Set displayname of participant |
externalId | Up to 36 alphanumeric characters (details) | Custom identifier for the participant. Can be searched in insights endpoints |
floatSelf | Nothing (on) or "off" | Float the self view to the bottom right |
groups | "Group Name(s)" - EX: "orange, banana, coconut" | Predefine up to 20 groups for the breakout groups function. |
lang | Nothing (en) or fr | it | de | nb | da | nl | pt | pl | es | hi | cs | zh-hant | jp | Set the meeting UI language to match your product or service. Select from either English en, French fr, Italian it, German de, Norwegian nb, Danish da, Dutch nl, Portuguese pt, Polish pl, Spanish es, Hindi hi, Czech cs, Chinese (Complex) zh-hant or Japanese jp. |
leaveButton | Nothing (on) or "off" | Enable/disable the leave button |
localization | Nothing (on) or "off" | Show/hide the language picker |
locking | Nothing (on) or "off" | Show/hide the room lock button and settings toggle |
logo | Nothing (on) or "off" | Show/hide the logo in the room header |
lowData | Nothing (on) or "off" | Use a lower resolution by default |
metadata | <string> | <string> gets passed on to the corresponding webhooks |
minimal | Nothing (on) or "off" | Apply minimal UI for embed scenarios |
moreButton | Nothing (on) or "off" | Show/hide the “…” button |
participantCount | Nothing (on) or "off" | Show/hide the participant counter |
people | Nothing (on) or "off" | Show/hide the participant list |
pipButton | Nothing (on) or "off" | Show/hide the Picture in Picture button |
precallCeremony | Nothing (on) or "off" | Determines if users see the pre-call device and connectivity test |
precallCeremonyCanSkip | Nothing (off) or "on" | Adds functionality for participants to skip the connectivity test |
precallPermissionHelpLink | <url> | Specify custom help link in pre-call review step pointing users to additional support pages |
room | A room URL | The full URL of the room you want to embed (required) |
roomIntegrations | Nothing (off) or "on" | Enables YouTube and Miro integrations in the meeting |
screenshare | Nothing (on) or "off" | Enable/disable screenshare |
skipMediaPermissionPrompt | Nothing (on) or "off" | Skips request permissions UI and asks for devices directly. Required for links used in Android Apps |
subgridLabels | Nothing (off) or "on" | Show/hide name labels in the subgrid |
timer | Nothing (on) or "off" | Show/hide the meeting timer |
toolbarDarkText | Nothing (on) or "off" | Sets button icon labels color to black. |
topToolbar | Nothing (on) or "off" | Used to toggle the entire top toolbar on/off. Top toolbar is hidden by default if using minimal |
video | "off" | Enter meeting with video off |
{% hint style="success" %}
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.
{% endhint %}
{% tabs %} {% tab title="Room w/ multiple customizations" %} {% code overflow="wrap" %}
<whereby-embed room="https://subdomain.whereby.com/your_room" displayName="John Smith" audio=off video=off background=off chat=off />{% endcode %} {% endtab %}
{% tab title="Basic room embed" %}
<whereby-embed room="https://subdomain.whereby.com/your_room" />{% endtab %}
{% tab title="Room w/ minimal UI" %} {% code overflow="wrap" %}
<whereby-embed room="https://subdomain.whereby.com/your_room" minimal />{% endcode %} {% endtab %} {% endtabs %}
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 | – |
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 } |
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}}{% hint style="warning" %} 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. {% endhint %}
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. |
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