Whereby developer guide

Want to learn more about embedding your one-time Whereby meeting rooms into your website or application? With our Meetings API you can customize your user experience to best meet your brand and customer needs.

Whether you’re hosting large group meetings or one-on-ones, the options to customize your meeting rooms are straightforward to integrate into your product, and individually adjustable by using URL parameters.

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. For more information, read our Additional functionality section.

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.

This last paragraph is worth repeating: you will get an error when trying the above command, since you don't own meeting id 1. This error means that it is working if it says "error":"Could not find meeting" (which is a 404 error). You can then try creating a meeting by using the command further down on this page.

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": "2020-01-01T01:00:00Z", "endDate": "2022-01-01T01: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 use your personal room for easy testing, or use the HTTP API to create the required roomUrl as you have to for production.

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

By adding ?embed to your meeting room link, you will get several UI adjustments. Namely, ?embed strips away some of the Whereby look and feel so that your brand shines. We recommend doing this any time you’re embedding your video meeting so that your participants experience your meeting as a part of your brand.

Along with the obvious Whereby branding and the top bar, this also removes several features, such as the name of the room, the number of participants, the recording button, the screenshare function and login button. Should you wish to add features back into your meeting room, you can do so by stacking URL parameters.

Embedding in a website

For initial development, since we don't allow localhost to be whitelisted, we suggest you add your domain to /etc/hosts. That way you can just use the actual domain instead of “localhost.”

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

Our API gives you the control to provide a customized experience for your events and meetings. You might even want to put in place different call parameters depending on who you’re meeting.

Plus, creating different parameters for different users within the same call is easily done by providing each participant a customized URL link. Each of the parameters you might want to change for your participants are simply added to the end of your meeting room URL.

For some participants it might be important that they join with their audio automatically switched off - ideal, for example, for students joining a classroom call. You can provide a link with that parameter included, and another without it included for your teacher or presenter. As long as your meeting room URL is the same, your users will enter the same room but with a customized experience for each user.

Stacking parameters

It is easy to use more than one parameter at a time for each meeting room or participant. In fact, you can use as many you want.

When there already is a parameter added to your meeting room URL, simply replace the question mark with the ampersand sign (&) to stack additional parameters. Say you want to use ?embed and ?screenshare in order to specifically turn screenshare back on, your end of the URL should look like this: ?embed&screenshare.

Supported 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
`?people=off`	Disable participant list
`?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.

Additional functionality

Audio

Like all of our parameters that you might want to tailor to your meeting room, the audio off parameter is simply typed onto the end of your meeting room URL. If you’re stacking it with the embed parameter, you would type ?embed&audio=off onto the end of your URL.

When a participant enters a meeting through a link with that URL parameter, their mic will automatically be off. If you don’t include the tag, their mic will automatically be on.

This is particularly useful if you’re in a classroom setting or there’s one person presenting to a large group, as it gives the presenter the courtesy of no distracting background sounds while they’re speaking and makes the experience smoother for everyone in the call.

Video

You might not require all participants to have their video on for your calls, so we have provided an option to start calls with the camera automatically off.

This might be helpful in cases where, for example, you have a sales representative showcasing product in a showroom scenario, where the customer at home doesn’t need to have their video on.

You would simply pass your customer the meeting room link with the video off parameter included in the URL. They can then see the host content, but relax knowing that they don’t have to turn their camera on.

Background

One of the most valuable parameters we offer for our embedded video meetings is the ability to turn the background off. While anyone with a Whereby account can adjust the background in your account settings, that would change the background for everyone and every single room in your account.

To customize your one-time embedded meeting room, simply use the background off parameter and the usual Whereby green background becomes transparent. This means that where your room is embedded on your site, your website page will appear as the background to your meeting room instead. You could even change the background of your website so you get a unique look every time.

We recommend that a background image is in place when you use this parameter, as the text that sits under each button (for video, audio, etc.) is white, so your users would not be able to see that text if you do not have a different coloured background.

Often, it’s helpful to change the background of your meeting room based on who’s in the call or the purpose of the call. Plus, with this parameter you can have any branding, colour scheme or image that lives on your website come through into your meeting room to help best relay your message.

Chat

When you embed your meeting room, the chat function is disabled as standard. There are some instances where you might prefer to have this still available, though.

Our chat function is safe and secure, and we don’t store the text from the chat after the meeting is over.

If you want to add it back into your embedded meeting rooms, simply add the chat on parameter to your URL, stacked with the embed parameter.

People

The participant list sidebar is enabled in the default embed scenario but the button to toggle it is only visible to the meeting host. The participant list may be of use as it provides access to tools to bulk manage participants. One reason you may want to disable the participant list completely is if you enable the chat function and don't want the participant list to show up as a second tab in the sidebar.

Leave button

Similar to the chat button, the leave button is automatically removed whenever you use the embed function. The reasoning behind this is that your embedded meeting room is meant to feel like it’s coming directly from your brand. There aren’t a huge number of cases where it’s relevant to include a leave button in this scenario, as when your call participants want to leave your meeting room, they can simply leave the page, hit the back button on their browser or close the tab.

If you do prefer to put the leave button back into your meeting room, you can enable it by using the leave on parameter. When your call participants do leave a call using this button, they’ll see a screen that says they’ve left.

Screenshare

Like the other parameters that are normally removed in the embed parameter, if you’d prefer to have screenshare capabilities for your meeting room, you can add the screenshare function back into your call. Simply add ?screenshare into your URL.

Once this button is enabled again, your call participants can share their full screen, a tab or a window. This will only work if the browser they’re using supports screenshare, something no mobile browsers supports yet.

Display name

The display name parameter allows you to choose the name displayed for any participant entering a call.

Most of the time when you’re embedding Whereby, it is likely that you would know who is joining your meeting room because your meetings will be scheduled, or they’ll be logged in your system, for example. So rather than asking each participant to input their display name, if you already have this information you can input it ahead of time by using the display name parameter on the specific URL link you would pass to that customer to join your meeting room.

This is a great way to put a little extra effort into your user experience, so that they don’t have to type their information in to your website more than once, for instance.

Record

Again, typically an embedded meeting room does not include a record button. If you require the record button, you can enable it again by stacking the recording on parameter with embed.

Guests to your meeting room will not see this; only the host is able to see the record button when the recording on parameter is used. You can make someone a host through a host URL.

Like all of our features, our recording function is secure because the recordings are stored locally on your machine.

Host privileges

With the Whereby meetings API, you can assign someone as the host is by providing them access to the room with a host room URL link. This will be functional between the start and end date of your meeting room.

This gives the participant who enters the meeting room through that URL host privileges, like locking the room and recording.

Remember, if you want a host to be able to record your meeting room when you’re also using the embed parameter, you need to give them both the host room URL as well as add the recording on parameter to their URL. This would be key for events or meetings with a large number of participants, for example a classroom scenario where the teacher is hosting the session.

Also useful in that case - the host has the ability to remove any participant, for example, someone who is behaving inappropriately.

Importantly, whenever a host refreshes their page, they will still have host room privileges as the URL remains the same.

The lifecycle of your room

When a Whereby room link is created, it is immediately available.

Behind the scenes, you will see that there is a start date and end date on each meeting room. As soon we get the request, we create the room link and deliver it back to you, regardless of when the start date is or when your meeting is scheduled for. Remember though, if you enter the room through the host room URL you will only have host room privileges between the start and end date. This is something to bear in mind when providing room links ahead of your scheduled meetings.

The end date is when the meeting ends. But take note, the meeting room is not deleted immediately in line with this date. That’s because we want to ensure that if your meeting runs over, even if only by a few minutes, your call is not timed out.

Instead, we delete meeting rooms no sooner than 24 hours after your room end date. In fact, meetings are deleted in bulk at 5am EST once your room is eligible for deletion, which is 24 hours after the end date. So, if your meeting is set to end at 11am on Tuesday, at 11am on Wednesday the room is eligible for deletion and it will be deleted on Thursday at 5am.

If you would prefer than your meeting room is deleted at the time of your end date, because you do not want people to be able to re-enter your meeting room that is also a possibility. You would simply delete the room yourself by using the HTTP API.