How to Customize Your Video Calls with Whereby Embedded

Upgrading to a Whereby Embedded account lets you create customizable video calls that reflect your brand. In earlier posts, we covered how to create video calls using the Whereby API and how to customize your meeting rooms by enabling or disabling features.

In this post, we'll show you how to change the look-and-feel of your virtual conference rooms. By the end of it, you'll know how to use Whereby Embedded as a white label video calling service.

What you'll need

• A Whereby Embedded account. Get started for free.

• The cURL library and a command-line application such as Terminal (macOS or Linux) or PowerShell (Windows) if you'd like to follow along with the examples in this post.

• A Whereby Embedded API key, again, if you'd like to follow along with the examples.

Whereby Embedded is a REST API. Although the examples here use cURL, you can interact with it using any programming language or library that supports HTTP.

Using the Whereby Dashboard

The easiest way to customize the look and feel of your video calls is by through the Appearance panel of the Whereby Dashboard's Configure screen. From the Appearance panel, you can set primary and secondary colors for your meeting rooms. You can also add a logo or change the meeting room and waiting room backgrounds.

Using the dashboard sets a default appearance for all of your rooms. But maybe you'd like to use a "Happy New Year" theme for your organization's January meeting. To change the theme for a single meeting, use the Room Theme API.

Using the Room Theme API

Whereby Embedded also lets you customize video calls using the API. Changes made using the API are applied per-room, and override the default settings for your account.

Create a room

First, you'll need to create a room, either using the Whereby dashboard or the REST API. From the dashboard, click the Create room button. You'll be prompted to select a room size; choose whether meetings should be recorded or streamed; and when your room should expire.

Once your meeting room is ready, take note of the identifier at the top of the screen. This is the room name.

You can also create a meeting room programmatically using the API, which makes it easier to embed Whereby in your applications.

Create an API key

To create a key, go to the Configure screen of the Whereby dashboard and click the Generate key button. Give your key a name when prompted. Use a name that helps you identify where your key will be used in case you need to remove it from your account.

Copy the API key to your clipboard. For local development, you can add it to your shell initialization file (typically ~/.profile, ~/.bash_profile, or ~/.zshrc).

export WHEREBY_API_KEY='<insert your key>'

Open a new Terminal window. You can now use $WHEREBY_API_KEY as a variable in shell scripts and command-line requests.

Keep in mind that API keys are only displayed once. You can generate more than one key, but you cannot recover an existing key.

Protect access to your API keys. Ensure that they aren't committed to your code repository. Consider using secret manager software to manage your keys.

Once you have a key and a room, you can use the API to change your room's appearance.

Room Theme API: An overview

Room Theme API endpoints begin with /rooms/{roomName}/theme/, where {roomName} is the identifier for an existing room. Each request to a Room Theme API must be a PUT request, and there are four endpoints:

• tokens : Set or change the primary and secondary room colors.

• logo : Set or change a meeting room logo.

• room-background : Set or change the meeting room background image or color.

• room-knock-page-background : Set or change the waiting room's background image or color.

For successful requests, the API returns a 204 No Content HTTP response and an empty body. You'll receive a 400 Bad Request response header and JSON-formatted error string for unsuccessful requests.

Setting room colors

To update the primary and secondary colors for a room, make a PUT request to /rooms/{roomName}/theme/tokens.

The request body must be a JSON-formatted string, containing two fields: tokensPreset and tokens. The tokens field should be an object that contains a colors field. Use the colors field to specify the primary and secondary room colors using RGB hexadecimal notation, as shown below.

curl https://api.whereby.dev/v1/rooms/{roomName}/theme/tokens \
  --request PUT \
  --header "Authorization: Bearer $WHEREBY_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- << EOF
  {
    "tokens": {
      "colors": {
        "primary": "#c09",
        "secondary": "#060"
      }
    },
    "tokensPreset": "custom"
  }
EOF

Both 3-character and 6-character hexadecimal values are supported. Four-character and 8-character hexadecimal values — RGBA values such as #0c0a — are not.

Adding a logo

If you'd like to add or change your room's logo, make a PUT request to /rooms/{roomName}/theme/logo. Send the image as a binary string with a Content-Type: multipart/form-data header. For cURL requests, this means using the -F or --form option, with a field named image, as shown below.

curl https://api.whereby.dev/v1/rooms/{roomName}/theme/logo \
  --request PUT \
  --header "Authorization: Bearer $WHEREBY_API_KEY" \
  --header "Content-Type: multipart/form-data" \
  --form image=@path/to/my_logo.png

Logo images should be at least 400 pixels wide, and use a bitmap file format. Whereby recommends PNG, but you can submit GIF, JPEG, or WebP images too. They'll be converted to PNG for display.

Setting a custom a meeting room or waiting room background image

Use the room-background and room-knock-page-background endpoints to set a custom background image for your meeting or waiting room. Like logos, background images should be bitmap images, ideally PNG. Background images should be at least 1400 pixels wide, and have a file size of 600KB or less. The example request below sets the meeting room background to my_room_background.png.

curl https://api.whereby.dev/v1/rooms/{roomName}/theme/room-background \
  --request PUT \
  --header "Authorization: Bearer $WHEREBY_API_KEY" \
  --header "Content-Type: multipart/form-data" \
  --form image=@path/to/my_room_background.png

Whereby Embedded provides the flexibility you need to create customized, branded video calls, meetings, and web-based seminars. Whether through the dashboard or the API, you can create virtual events that reflect your organization's identity.

Create customized video calls and virtual meetings with Whereby Embedded. Get started for free. No credit card is required.