# Web Component Reference ## Installation When using React or a bundler like Webpack, Rollup, Parcel, etc ```bash npm install @whereby.com/browser-sdk ``` ```javascript import "@whereby.com/browser-sdk/embed" ``` {% tabs %} {% tab title="HTML" %} {% code overflow="wrap" %} ```html ``` {% endcode %} You can use a `hostRoomUrl` instead of the `roomUrl`, if you want to give the user [host privileges](/whereby-product-features/user-roles-and-privileges.md#hosts) {% endtab %} {% tab title="JSX" %} ```jsx const MyComponent = ({ roomUrl }) => { return } export default MyComponent ``` You can use a `hostRoomUrl` instead of the `roomUrl`, if you want to give the user [host privileges](/whereby-product-features/user-roles-and-privileges.md#hosts) {% 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](/whereby-for-web-browser/web-component-and-pre-built-ui/web-app-quickstart.md#using-a-less-than-script-greater-than-element) in your site {% endhint %} ### 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.

{% hint style="success" %} There are additional room customizations and options that can be found in the [URL parameters](/whereby-for-web-browser/web-component-and-pre-built-ui/configuring-with-attributes.md) 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 %} #### Usage examples {% tabs %} {% tab title="Room w/ multiple customizations" %} {% code overflow="wrap" %} ```html ``` {% endcode %} {% endtab %} {% tab title="Basic room embed" %} ```html ``` {% endtab %} {% tab title="Room w/ minimal UI" %} {% code overflow="wrap" %} ```html ``` {% endcode %} {% endtab %} {% endtabs %} ### Listening to events You can listen for events on the `` 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: ```javascript 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: ```javascript 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 {% hint style="warning" %} For this feature to work, you must add the origin of your application to the "[Allowed domains](/further-resources/faq-and-troubleshooting/allowed-domains-and-localhost.md)" section in your Whereby account. If not present, the following methods will not do anything. {% endhint %} The `` 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: ```javascript 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.whereby.com/reference/using-the-whereby-embed-element.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.