Using the REST API
Create or delete Whereby rooms programmatically using a simple API request. Rooms can be created on demand, or ahead of time for scheduled meetings.
Note: To use the API, you’ll need to create an API key. A new key is generated from the “Configure” section in the Embedded dashboard. Your API key is secret and should only be used from your server.
Creating rooms
Once you have secured your API key, you can create a room by sending an HTTP request with the necessary parameters in the body. Available parameters and formats can be found in the API reference.
endDate is interpreted as UTC by default, but other time zones are supported by including an offset in hours and minutes. For example, Eastern Standard Time (EST) would be expressed as 2099-08-11T07:56:01-05:00.Rooms are fully functional from the time they are created.
cURL
PHP
Node
Python
Java
1
curl https://api.whereby.dev/v1/meetings \
2
--header "Authorization: Bearer $YOUR_API_KEY" \
3
--header "Content-Type: application/json" \
4
--request POST \
5
--data @- << EOF
6
{
7
"endDate": "2099-02-18T14:23:00.000Z",
8
"fields": ["hostRoomUrl"]
9
}
10
EOF
Copied!
1
$api_key = "YOUR_API_KEY";
2
$ch = curl_init();
3
curl_setopt($ch, CURLOPT_URL, 'https://api.whereby.dev/v1/meetings');
4
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
5
curl_setopt($ch, CURLOPT_POST, 1);
6
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
7
"endDate": "2099-02-18T14:23:00.000Z",
8
"fields": ["hostRoomUrl"]}'
9
);
10
11
$headers = [
12
'Authorization: Bearer ' . $api_key,
13
'Content-Type: application/json'
14
];
15
16
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
17
$response = curl_exec($ch);
18
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
19
20
curl_close($ch);
21
22
echo "Status code: $httpcode\n";
23
$data = json_decode($response);
24
echo "Room URL: ", $data->{'roomUrl'}, "\n";
25
echo "Host room URL: ", $data->{'hostRoomUrl'}, "\n";
Copied!
1
const fetch = require("cross-fetch");
2
3
const API_KEY = "YOUR_API_KEY";
4
5
const data = {
6
endDate: "2099-02-18T14:23:00.000Z",
7
fields: ["hostRoomUrl"],
8
};
9
10
function getResponse() {
11
return fetch("https://api.whereby.dev/v1/meetings", {
12
method: "POST",
13
headers: {
14
Authorization: `Bearer ${API_KEY}`,
15
"Content-Type": "application/json",
16
},
17
body: JSON.stringify(data),
18
});
19
}
20
21
getResponse().then(async res => {
22
console.log("Status code:", res.status);
23
const data = await res.json();
24
console.log("Room URL:", data.roomUrl);
25
console.log("Host room URL:", data.hostRoomUrl);
26
});
27
Copied!
1
import requests
2
import json
3
4
API_KEY = "YOUR_API_KEY"
5
6
data = {
7
"endDate": "2099-02-18T14:23:00.000Z",
8
"fields": ["hostRoomUrl"],
9
}
10
11
headers = {
12
"Authorization": f"Bearer {API_KEY}",
13
"Content-Type": "application/json",
14
}
15
16
response = requests.post(
17
"https://api.whereby.dev/v1/meetings",
18
headers=headers,
19
json=data
20
)
21
22
print("Status code:", response.status_code)
23
data = json.loads(response.text)
24
print("Room URL:", data["roomUrl"])
25
print("Host room URL:", data["hostRoomUrl"])p
Copied!
1
import com.fasterxml.jackson.databind.ObjectMapper;
2
3
import java.net.URI;
4
import java.net.http.HttpClient;
5
import java.net.http.HttpRequest;
6
import java.net.http.HttpResponse.BodyHandlers;
7
import java.util.Collections;
8
import java.util.Map;
9
10
var apiKey = "YOUR_API_KEY";
11
var data = Map.of(
12
"endDate", "2099-02-18T14:23:00.000Z",
13
"fields", Collections.singletonList("hostRoomUrl")
14
);
15
var request = HttpRequest.newBuilder(
16
URI.create("https://api.whereby.dev/v1/meetings"))
17
.header("Authorization", "Bearer " + apiKey)
18
.header("Content-Type", "application/json")
19
.POST(HttpRequest.BodyPublishers.ofString(new ObjectMapper().writeValueAsString(data)))
20
.build();
21
22
var response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
23
System.out.println("Status code: " + response.statusCode());
24
System.out.println("Body: " + response.body());
25
Copied!
201 Response: Success
1
{
2
"meetingId": "1",
3
"startDate": "2022-02-17T14:24:00.000Z",
4
"endDate": "2099-02-18T14:23:00.000Z",
5
"roomUrl": "https://example.whereby.com/room",
6
"hostRoomUrl": "https://example.whereby.com/room?roomKey=eFhcG...i00ZG"
7
}
Copied!
401 response: API key missing or invalid
Deleting rooms
For many scenarios, it makes sense to create rooms to be used for a limited time or even just a single meeting, after which the rooms should be deactivated. With each room having a unique URL and a limited lifespan, there's no need to worry about meetings conflicting or rooms being used for other purposes after the intended session.
When creating a room using the API, the
endDate parameter is used to indicate the time at which the room should be marked for deactivation. The room will then automatically be deleted within 24 hours of the endDate provided. Webhook events and hostRoomURL privileges will also end an hour after the endDate is met.
Last modified 1mo ago
Copy link