How to Create a Room Using Whereby's Video Chat API

The Whereby API makes it easy for developers to create a video chat app with WebRTC and a few lines of code. You can use it to instantly create video calls and virtual meeting rooms, saving weeks of development time. In this post, we'll take a look at how to create a meeting room using the Whereby Embedded REST API.

What you will need

• A Whereby Embedded account. You can try it for free.

• The cURL library, if you'd like to try the examples in this post.

• A command line application such as Terminal (macOS and Linux), iTerm2 (macOS), or PowerShell (Windows)

You can use the library and language of your choice with Whereby's API. Our documentation includes examples using cURL, PHP, Node, Python and Java. We'll use cURL in the examples here.

Create an API Key

Log in to your Whereby Embedded account, and visit the Configure screen. Use the Generate key button to create a new API key for your account.

Once you've created your key, copy it and save it somewhere safe. 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. If you use .env files to store credentials, ensure that you don't accidentally commit it to your code repository.

For local development and testing, add your API key to your shell initialization file. macOS and Linux users can find this file in their home directory. It's typically named ~/.profile, ~/.bash_profile, or ~/.zshrc.

export WHEREBY_API_KEY='<insert your key>'

Once you've edited the file, open a new terminal window. You can now use $WHEREBY_API_KEY as a variable in shell scripts and cURL requests. Confirm this by typing echo $WHEREBY_API_KEY at the command line prompt.

Request a Room

Whereby uses bearer or token authentication for API requests. Each API request must include an Authorization: request header with a value of Bearer <token>, where <token> is your Whereby API key.

To create a room, make a POST request to the /meetings API endpoint. Pass parameters as a JSON-formatted string, with the appropriate request header. What follows is an example cURL request.

curl https://api.whereby.dev/v1/meetings \
  --request POST \
  --header "Authorization: Bearer $WHEREBY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "endDate": "2032-12-31T18:32:58-05:00" }'

The endDate parameter is the only required argument when creating a room. endDate can be:

• a date string such as 2032-12-31 or Dec 31, 2032;

• a date and time string such as Dec 31, 2032 14:23 or 2022-06-16 02:00:00; or

• a string containing a date, time, and time zone offset, such as 2032-12-31 02:00:00-500, Jan 01, 2023 00:00:00-800 or 2032-12-31T18:32:58-05:00.

Whereby's API uses UTC as its default time zone. If endDate lacks a time zone offset, it will be interpreted as a UTC date-time. It's best to include the offset to remove ambiguity and reduce the risk of date-related errors in your application. Meetings are automatically deleted one hour after the specified end date.

The API response

If your meeting request was successful, you'll get a JSON-formatted string response that's similar to the one below.

{
    "startDate": "2022-06-15T22:53:12.122Z",
    "endDate": "2032-12-31T23:32:58.000Z",
    "roomUrl": "https://example.whereby.com/d51530d1-c9ef-4a5f-8e99-890cac252cec",
    "meetingId": "56879110"
}

Share the roomURL with your meeting's participants. Rooms are available as soon as they're created. Anyone with the URL can enter the meeting room at any time.

Creating hosted rooms and webinars

You can also use the Whereby API to create hosted rooms and webinars. You'll to add a fields parameter to your API request. The fields parameter must be an array that contains"hostRoomUrl", "viewerRoomUrl" or both.

curl <https://api.whereby.dev/v1/meetings> \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --request POST \
  --data @- << EOF
{
  "endDate": "2032-12-31T18:32:58-05:00",
  "fields": ["hostRoomUrl", "viewerRoomUrl"]
}
EOF

Here's the response. It contains two additional fields: hostRoomUrl and viewerRoomUrl.

{
    "startDate": "2022-06-16T00:40:00.261Z",
    "endDate": "2032-12-31T23:32:58.000Z",
    "roomUrl": "https://example.whereby.com/9e20324d-817f-4d9d-9a34-2dded958cb0d",
    "meetingId": "56879747",
    "hostRoomUrl": "https://example.whereby.com/9e20324d-817f-4d9d-9a34-2dded958cb0d?roomKey=eyJhGciOi...aAaCk",
    "viewerRoomUrl": "https://example.whereby.com/9e20324d-817f-4d9d-9a34-2dded958cb0d?roomKey=eyJhbGciO...SNKY"
}

Users that join using the hostRoomUrl become hosts of the meeting room. Hosts can:

• lock the meeting room;

• approve attendees; and

• mute or remove meeting participants.

Users that join using the viewerRoomUrl can watch a meeting. They aren't able to join with audio or video, although they can still participate in the meeting room chat.

Learn more

Now that you’ve created a Whereby room, you can embed your Whereby room into your website, platform or app. Follow our step-by-step video on embedding your video calls into your website.

Whereby Embedded also has built-in features that can be configured and optimized, such as recording, streaming, breakout groups and more. Set these options for your meeting as part of the creation request.

Find out more in our dev docs or watch our get started videos on Youtube.

Get started with the Whereby API for free. Add video to your web site or application today. No credit card is required, and 2,000 participant minutes are included every month.