LogoLogo
WherebyStatusCommunity
  • ๐Ÿ“นWhereby 101
    • Create Your Video Experience
      • Get started in 3 steps
      • Embedding Whereby in a web app
        • Using Whereby's Web Component & Pre-built UI
          • Script Tags
          • With Low Code
            • Embedding in Squarespace or Wordpress
            • No code video conferencing in Bubble
        • Using Whereby's Browser SDK with React Hooks for a fully custom UI
      • Embedding Whereby in a mobile app
        • Embedding Whereby in iOS
          • Using Whereby's Native iOS SDK
        • Embedding Whereby in Android
          • Using Whereby's Native SDK
        • Using Flutter
        • Using React Native
      • Github SDK Examples
      • Meeting scheduling with Cronofy
    • Generating Room URLs
      • Name prefixes
      • Using โ€œCreate a roomโ€
      • Using Postman
    • Customize Your Video Experience
      • During room creation
      • Using Attributes/URL Params
      • Global preferences
      • Branding elements
      • Dial-In
      • File sharing
      • Breakout Groups with Embedded
      • Waiting Rooms
    • User roles & Meeting Permissions
    • FAQ
      • Accessibility
      • Whereby Words
      • Firewall & Security
      • HIPAA compliant setup
      • Allowed Domains & Localhost
      • Whereby Embedded Feature Comparison
  • ๐Ÿ”Meeting Content & Quality
    • Recording
      • Cloud Recording
      • Local Recording
    • Transcribing
      • Session Transcription
      • Recording Transcription
    • Live Captions
    • Session summaries
    • Live streaming RTMP
    • Quality Insights
      • Real-time troubleshooting
      • Using the Insights dashboard
      • Improving call quality
      • Tracking room events with Webhooks
  • ๐ŸคทEnd User
    • End User Support Guides
      • Supported Browsers & Devices
      • Screen Sharing Setup & Usage
      • Using Breakout Groups
      • Troubleshooting & Basics
  • ๐ŸššDeveloper Guides
    • Quickly deploy Whereby to your domain
    • Tracking Customer Usage
    • Migrating from Twilio
      • Twilio JS SDK Quick Migration
      • Twilio JS SDK Direct Migration
  • ๐Ÿ–ฅ๏ธReference
    • REST API Reference
      • /meetings
      • /insights
      • /recordings
      • /transcriptions
      • /summaries
      • /rooms
    • Web Component Reference
    • React Hooks Reference
      • Quick Start
        • Getting started with the Browser SDK
      • Guides & Tutorials
        • Migrate from version 2.x to 3
        • Grid logic
        • Custom Video Tiles with React
        • Usage with Next.js
        • How to customize the toolbar
      • API Reference
        • WherebyProvider
        • VideoView
        • VideoGrid
        • useLocalMedia
        • useRoomConnection
      • Types
    • React Native Reference
      • Quick Start
      • WherebyEmbed
    • Webhooks Reference
Powered by GitBook
On this page
  • Installation
  • Attributes of the component
  • Listening to events
  • Sending commands

Was this helpful?

Edit on GitHub
  1. Reference

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.

Last updated 3 months ago

Was this helpful?

Installation

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

npm install @whereby.com/browser-sdk
import "@whereby.com/browser-sdk/embed"
<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

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

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

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"

breakout

Nothing (on) or "off"

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

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"

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

Usage examples

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

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 }

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

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

Automatically spotlight the local "" on room join

Hide the entire bottom tool bar. Useful if creating buttons using

Show/hide the for the meeting host.

Up to 36 alphanumeric characters ()

Skips request permissions UI and asks for devices directly. Required for links used in

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

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

๐Ÿ–ฅ๏ธ
URL parameters
Allowed domains
Breakout Groups feature
Android Apps
commands
simple Script tag
host privileges
host privileges
host
details