Create

To create a new room you need to execute a POST request against the /rooms endpoint.

The only required field is the privacy field, which accepts "public" and "private" values.

Public rooms can be accessed by everyone who knows the room URL. They are easy to start with and you can invite people by giving them the room URL.

Private rooms on the other hand can be accessed only by having a valid Token. They are generally more secure, because even if you know the room URL, you cannot enter inside without having a valid issued token.

To enable end-to-end encryption (e2ee) use the e2ee_enabled flag when creating or editing the room.

If you are doing moderated meetings or webinars you would want to specify the roles field. By default you are provided with three roles in your team - moderator, speaker and attendee which should be enough for most needs. Also if there is more than one role in your room, you must specify the default_role field. About roles/permissions details -> read here.

There are a lot more room fields you can configure. For a full list -> read here.

If you don't provide a friendly_url in the request, then the API will auto-generate one.

1. Request (will auto-generate room URL)

cURL

curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"privacy": "public"}'

Java

import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

String TEAM_ID = "YOUR_TEAM_ID";
String DEVELOPER_KEY = "YOUR_DEVELOPER_KEY";
String authorizationHeader = "Bearer " + Base64.getEncoder().encodeToString((TEAM_ID + ":" + DEVELOPER_KEY).getBytes());

Map<String, String> data = Map.of("privacy", "public");
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Body: " + response.body());

Response (200 OK)

{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "l5zIyafmlEFMPKA",
  "privacy": "public",
  ....................
}

As you can see a friendly_url was auto-generated and the public room will be accessible at https://teamNameHere.digitalsamba.com/l5zIyafmlEFMPKA

2. Request (will use the friendly_url you provided)

cURL

curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"privacy": "public", "friendly_url": "my-test-meeting"}'

Java

import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

String TEAM_ID = "YOUR_TEAM_ID";
String DEVELOPER_KEY = "YOUR_DEVELOPER_KEY";
String authorizationHeader = "Bearer " + Base64.getEncoder().encodeToString((TEAM_ID + ":" + DEVELOPER_KEY).getBytes());

Map<String, String> data = Map.of(
  "privacy", "public",
  "friendly_url", "my-test-meeting"
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Body: " + response.body());

Response (200 OK)

{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "my-test-meeting",
  "privacy": "public",
  ....................
}

The newly created meeting will be available at the url you specified: https://teamNameHere.digitalsamba.com/my-test-meeting

3. Request (a room with moderator, speaker and attendee roles)

cURL

curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
     "privacy": "public", 
     "roles": ["moderator", "speaker", "attendee"], 
     "default_role": "attendee"
  }'

Java

import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

String TEAM_ID = "YOUR_TEAM_ID";
String DEVELOPER_KEY = "YOUR_DEVELOPER_KEY";
String authorizationHeader = "Bearer " + Base64.getEncoder().encodeToString((TEAM_ID + ":" + DEVELOPER_KEY).getBytes());

Map<String, Object> data = Map.of(
  "privacy", "public",
  "roles", new String[] {"moderator", "speaker", "attendee"},
  "default_role", "attendee"
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Body: " + response.body());

Note how the default_role needs to be specified when there is more than one role in the room. The default role is the role being used if a participant visits the public room without a token, or there is no role specified in the token. In general the least powerful role should be the default one, because you should not want participants to enter by default as moderators.

Response (200 OK)

{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "l5zIyafmlEFMPKA",
  "privacy": "public",
  "roles": [
        {
            "id": "76bb6199-2900-4b8d-b1bf-351dec4a8db4",
            "name": "moderator",
            "display_name": "Moderators"
        },
        {
            "id": "e5bad6b9-48bd-46a0-9482-af78a834c28c",
            "name": "speaker",
            "display_name": "Speakers"
        },
        {
            "id": "8cae6c49-c40a-4965-a32b-6cf20de36755",
            "name": "attendee",
            "display_name": "Attendees"
        }
  ],
  "default_role": {
      "id": "8cae6c49-c40a-4965-a32b-6cf20de36755",
      "name": "attendee",
      "display_name": "Attendees"
  },
  ....................
}