Whereby developer guide

Getting started

We have two different parts to the API. You can use them together, or just one of them:

Creating meetings using the HTTP meetings API from a server.
Embedding meetings using an <iframe> or in a mobile app

In order to integrate with Whereby, there are a couple of things which needs to be set up. For creating meetings you'll need an API key. If you are planning to embed in another web service, we will have to whitelist the domains you'll use (except for local development/testing).

Get in touch when you need this.

1. Creating meetings

Verifying your API key works

Once you have retrieved an API key from Whereby, you can verify it is correct by issuing the following command in your terminal:


            curl -H "Authorization: Bearer YOUR_API_KEY" https://api.whereby.dev/v1/meetings/1

A 200 or 404 response status indicates your key is working. A 401 response means the provided key is incorrect.

Using the meetings API

Meetings are created by sending sending an HTTP request to our servers. Reference our http api docs to learn how to format your requests. If successful, the response will contain the URL of the newly created meeting, which can be shared through email, SMS etc, or embedded into a website as described below.

Only use this from your server. Since this API requires your secret API key, you'll need to call it from your own servers. You can not call this API from clients (browser/app). If you want to do that, then you'll need to create your own endpoint on your own api server to do that.

A quick example on how to create a one-time room for a meeting:


            curl -X POST \

            -d '{"startDate": "2030-01-01T02:00:00Z", "endDate": "2030-01-01T03:00:00Z", "fields": ["hostRoomUrl"]}' \

            -H "Content-Type: application/json" \

            -H "Authorization: Bearer YOUR_API_KEY" \

            https://api.whereby.dev/v1/meetings

Go to HTTP api reference docs

2. Embedding meetings

You can embed Whereby in your own web service or in your native app. Embedding is only available through our Meetings API plan.

The embed source needs to be a Whereby meeting URL (also called room link). You can create that manually (easy for testing), or use the HTTP API to create the required roomUrl.

Either approach allows for customization of the embedded experience by adding query parameters to the room URL.

Embedding in a website

For initial development install an extension like disable CSP (Chrome). When you're ready for production or staging, we'll need to whitelist the domains.

Your development environment will still need to use https.

The following example shows how to embed a Whereby meeting for subdomain example and room room in a website:


            <iframe
            src="https://example.whereby.com/room?embed&iframeSource=example"

            allow="camera; microphone; fullscreen; speaker; display-capture"></iframe>

The iframeSource parameter is required and must be set to your Whereby subdomain, not your domain. The embed is not required, you can find more URL parameters to customize Whereby further down.

Whitelisting your domains

Once you want your embed to work without a CSP-disabling extension, you'll need your domains whitelisted. If your web service is at https://www.example.com, you can provide that, or ask us to whitelist a wildcard, like https://*.example.com which will work for www but also any other subdomain directly under the main domain. It is not recursive, but will work with any address after the hostname.

Do note, however, that if your website is https://example.com, you need to whitelist this specifically as the *. wildcard won't catch that. So if you want to use Whereby on both https://staging.example.com/my-page and on https://example.com/production-page/123, you need to ask us to whitelist both, like: https://example.com https://*.example.com

Verify your domain is whitelisted

curl --head 'https://YOUR_SUBDOMAIN.whereby.com?iframeSource=YOUR_SUBDOMAIN'

If whitelisted, the response of this command should list out your service URL in the Content-Security-Policy section.

You must pass ?iframeSource=YOUR_WHEREBY_SUBDOMAIN to the room URL to instruct Whereby servers to pass required CSP headers to the browser.

On the iframe itself, you need to set the allow attribute to allow Whereby to get access to cam / mic: allow="camera; microphone; fullscreen; speaker".

You also need to use https (also in development) for some browsers to give you access all the web APIs Whereby use.

URL parameters

`?embed`	Apply default UI adjustments for embed scenarios
`?displayName=<participant_name>`	Set displayname of participant
`?audio=off`	Enter meeting with audio off
`?video=off`	Enter meeting with video off
`?background=off`	Render without background to let embedding app render its own
`?chat=<on\|off>`	Enable/disable chat
`?leaveButton=<on\|off>`	Enable/disable leave button
`?recording=<on\|off>`	Enable/disable recording (only for host)
`?screenshare=<on\|off>`	Enable/disable screenshare

Embedding in native apps

Android

Embedding in an Android app requires use of the WebView class.

You need to override “WebChromeClient.onPermissionRequest” and use the ?skipMediaPermissionPrompt query parameter on the embedded URL to make Whereby be able to get the camera.

iOS

Although Safari has a WKWebView component which lets developers embed websites into an iOS app, this sadly does not work when embedding pages leveraging the WebRTC technology Whereby is built on. This leaves two options for native iOS apps:

Redirect to mobile Safari
Use SFSafariViewController

If you need your own UI at the same time as the Whereby-meeting, it would be possible to use SFSafariViewController to embed a website where you show your UI and again use an iframe to embed Whereby.

If you are using Cordova, you can use a Cordova plugin for SafariViewController.

Customizing the room

You can customize your room by using URL parameters in the same way as embedding in a website.