Embedded
developer guide

Whereby Embedded is an easy-to-use video meetings API for websites. Embed video meetings into an application or website with the Rest API allowing your team to build faster and ship more often.

Get started

Anchor link for how to start a meeting

An API key is needed to use the Embedded API. A new key is generated from “Account settings” in your organization’s dashboard. API keys can be renamed and deleted.

Create a meeting by sending a HTTP request to Whereby’s servers from your server. A successful response contains a roomUrl. Your API key is secret and should only be used from your server. Create a meeting.

Embed a meeting in your website or app with an iFrame. The iFrame’s src attribute is specified as the roomUrl. You can customize the meeting with URL parameters.

Whereby REST API

Anchor link for Embed a meeting

Create a meeting with a HTTP request containing your API key sent from your server to Whereby’s. The response contains a roomUrl that is embedded in your client within an iFrame.

Calling Whereby’s API from your client should be done through an endpoint on your server. This will help keep the API key safe from exposing it to users. For this reason, the API does not return an Access-Control-Allow-Origin header in its response.

Create a meeting

Anchor link for how to create a meeting

A quick example showing how to create a room. Explore more in the API docs↗.

curl https://api.whereby.dev/v1/meetings \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --request POST \
  --data @- << EOF
{
  "startDate": "2020-08-11T07:56:01Z",
  "endDate": "2020-08-11T07:56:01Z",
  "fields": ["hostRoomUrl"]
}
EOF
$api_key = "YOUR_API_KEY";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.whereby.dev/v1/meetings');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "startDate": "2020-08-11T07:56:01Z",
  "endDate": "2020-08-11T07:56:01Z",
  "fields": ["hostRoomUrl"]}'
);

$headers = [
  'Authorization: Bearer ' . $api_key,
  'Content-Type: application/json'
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);

curl_close($ch);
const fetch = require("node-fetch");

const API_KEY = "YOUR_API_KEY";

const data = {
  startDate: "2020-08-11T07:56:01Z",
  endDate: "2020-08-11T07:56:01Z",
  fields: ["hostRoomUrl"],
};

(async () => {
  const response = await fetch("https://api.whereby.dev/v1/meetings", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });
})();
import requests

API_KEY = "YOUR_API_KEY"

data = {
    "startDate": "2020-08-11T07:56:01Z",
    "endDate": "2020-08-11T07:56:01Z",
    "fields": ["hostRoomUrl"],
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.whereby.dev/v1/meetings",
    headers=headers,
    json=data
)
{
    "meetingId": "1",
    "startDate": "2020-01-01T02:00:00.000Z",
    "meetingId": "2020-01-01T03:00:00.000Z",
    "roomUrl": "example.com",
    "hostUrl": "example.com"
}

401 Response: API key missing or invalid

Embed a meeting

Anchor link for how to embed a meeting

Embedding a meeting into a service or app requires using an iFrame with the src attribute specified as the roomUrl. The iFrameSource parameter should to be set to your Whereby subdomain. Check if a subdomain has been allowed.

<iframe
  src="https://subdomain.whereby.com/room?embed&iframeSource=subdomain"
  allow="camera; microphone; fullscreen; speaker; display-capture"
/>

Embedding in Android

Anchor link for embedding in android

Embedding in Android requires use of the WebView class. The following method should be overriden WebChromeClient.onPermissionRequest in combination with ?skipMediaPermissionPrompt url parameter to allow Whereby access the camera.

Embedding in iOS

Anchor link for embedding in iOS

Currently WKWebView does not work when embedding pages that use WebRTC. It is recommended to use one of the following options:

  • Redirect to mobile Safari.
  • Use SFSafariViewController to open a website containing an iFrame with it’s src specfied as a Whereby meeting, alongside a custom user interface.

To use Whereby with Cordova (Phonegap) please use the plugin for SafariViewController

Meeting customization

Anchor link for meeting customzation

Meeting customization is achieved with url parameters for each iFrame instance. It’s possible for each participant in a meeting to have different parameter combinations. Learn more about combining parameters.

URL ParameterDescription
?embedApply default embedded UI
?video=offParticipant joins the meeting with camera turned off
?audio=offParticipant joins the meeting with microphone turned off
?screenshare=<on|off>Show/hide the screenshare button
?chat=<on|off> Show/hide the chat button
?people=off Hide the people button
?leaveButton=<on|off>Show/hide the leave button
?displayName=<name> Set display name of paticipant
?background=offHide the meeting background

Property details

?embedAnchor link for ?embed

The embed parameter applies a combination of UI adjustments to simplify the meeting interface.

Hidden items: Status bar, chat button, screensharing button, leave button, and Whereby’s branding.

Shown items: Video and audio buttons.

For further adjustments, additional parameters can be combined with ?embed. For example ?embed&chat=on will show the chat button.

?video=offAnchor link for ?video=off

Participants join the meeting with their camera off, they can turn it on whenever they want.

Usecase: A sales representative showcasing a product to a customer relaxing at home.

?audio=offAnchor link for ?audio=off

Participants join the meeting with their microphone off, they can turn it on whenever they want.

Usecase: A presentation is being given in a big meeting where attendees are not expected to participate verbally.

?screenshare=<on|off>Anchor link for ?screenshare=<on|off>

Show/hide the screensharing button for the meeting participant.

Screensharing is available on all browsers that support this natively. Currently no mobile browsers support screensharing.

?chat=<on|off>Anchor link for ?chat=<on|off>

Show/hide the chat button. Messages are not stored after the meeting has ended.

?people=offAnchor link for ?people=off

Hide the people button.

Usecase: The people button shows the participant list, which can be useful for bulk management of participants in bigger meetings.

?displayName=<name>Anchor link for ?displayName=<name>

Set the display name for a participant instead of prompting the user for this information.

Usecase: A particpant’s name may be known before they join the meeting. Including this information as a parameter will save the user from entering their name again.

?background=offAnchor link for ?background=off

Hide the default meeting background.

Usecase: Hiding the meeting background allows the meeting to appear more intregated by allowing the app or service’s branding shine through as the new background.

Combining parameters

Anchor link for combining parameters

Further customize the meeting by combining parameters by using the ampersand symbol (&). The following example combines the embed with screenshare=off and people=off

https://subdomain.whereby.com/room?embed&screenshare=off&people=off

Host privileges

Anchor link for host privileges

Hosts join the meeting with the hostUrl. They are granted access to features such as locking the meeting. These features may need to be added to the embed url by combining url parameters. Additionally the host has privilegers to remove participants.

An example of the returned .json containing the hostUrl. Explore more in the API docs↗.

{
    "meetingId":"1",
    "startDate":"2020-01-01T02:00:00.000Z",
    "endDate":"2020-01-01T03:00:00.000Z",
    "roomUrl":"example.com",
    "hostUrl":"example.com"
}

Localhost

Anchor link for testing with localhost

Currently, embedding on localhost is not supported. Alternatively it is possible to redirect a local DNS name to 127.0.0.1 by adding an entry to the /etc/hosts file, and checking if the subdomain is allowed.

If a self-signed certificate is used for testing, the browser will need to trust it, and your development environment will need to use HTTPS.

Troubleshooting

Anchor link for troubleshooting

Verify a API key

Check if an API key is valid with the simple interface below. Alternatively use cURL from either a terminal window or server.

curl https://api.whereby.dev/v1/hello \
  --head \
  -H "Authorization: Bearer API_KEY"

A 200 response indicates the API key is working. A 401 response means the provided key is incorrect.

Check if a subdomain has been allowed

Enter a subdomain and run the cURL command in a terminal window.

curl --head "https://YOUR_SUBDOMAIN.whereby.com"

A successful response is indicated with your allowed domains included in the Content-Security-Policy’s header.