Whereby developer guide

Getting started

In order to integrate with Whereby, there are a couple of things which needs to be set up. A Whereby account with a subdomain API key - This key allows you to create meetings on the Whereby service. Get in touch if you’re missing this. If you are planning to embed in another web service, we will have to whitelist the hostname of your service. While in development however, you can use a Chrome extension to bypass this requirement locally on a development machine:

Chrome extension

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.

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.

Creating meetings

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.

Embedding meetings

Meeting urls created using our API can be embedded in two ways; in a native app, or in an existing website. Either approach allows for customization of the embedded experience by adding query parameters to the room url.

Url parameters

  • ?embed - Apply default UI adjustments for embed scenarios
  • ?displayName - Set displayname of participant
  • ?audio=off - Enter meeting with audio off
  • ?video=off - Enter meeting with video off
  • ?chat=<on> - Enable chat in embedded meeting
  • ?screenshare=<on> - Enable screenshare in embedded meeting

Embedding in native apps

Android

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

iOS

Although Safari has a UIWebView 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 SFSafariViewControlleri

Embedding in a website

Whereby meetings are embedded into other web services by use of an iframe. The source of the iframe needs to be a Whereby meeting url, which is obtained from our API. In addition to the url parameters described above, the following query parameters will have to be added:

Required url parameters

  • ?iframeSource=YOUR_WHEREBY_SUBDOMAIN - Instruct Whereby servers to pass required CSP headers to the browser

On the iframe itself, there are a couple of attributes which needs to be set in order to allow Whereby to get access to cam / mic.

Required iframe attributes

  • allow="camera;microphone;fullscreen;speaker"

Example

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

<iframe src="https://YOUR_SUBDOMAIN.whereby.com/API_GENERATED_MEETING_ID?embed&iframeSource=YOUR_SUBDOMAIN" allow="camera;microphone;fullscreen;speaker" />