Create

To create a new role you need to execute a POST request against the /roles endpoint.

The following fields need to be set:

• name -> internal unique name to reference the role in rooms and tokens

• display_name -> the display name people will see visually inside the participants list

• permissions -> a JSON object of the permission names this role is allowed to have. Allowed permissions have true as a value. For role sensitive permissions like remote_muting you can additionally specify an array with the role names which the participant is allowed to operate on. For example you can make a Speaker be allowed to remote mute an Attendee, but not remote mute a Moderator. If you don't specify the array (and just put true), that means the participant is allowed to operate on all roles (current and future). That gives you full flexibility.

• description (optional) -> text description if you want to add some explanations

Creating a role doesn't immediately assign it to any rooms. You need to specify the available roles inside a room during room creation. If all of your rooms will have the same roles it may be easier for you to set these roles in the default team settings, so all rooms will inherit the same default roles.

Request

cURL

curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/roles \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
     "name": "custom", 
     "display_name": "Custom", 
     "permissions": {
        "start_session": true, 
        "remote_muting": ["speaker", "attendee"],
        "raise_hand": true
     } 
  }'

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(
  "name", "custom",
  "display_name", "Custom",
  "permissions", Map.of( "start_session", true,
		         "remote_muting", new String[] {"speaker", "attendee"},
		         "raise_hand", true
		 )
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/roles"))
  .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": "2d9448b9-d9ee-4102-b31a-f83ab4af2af8",
    "name": "custom",
    "display_name": "Custom",
    "description": null,
    "default": false,
    "created_at": "2023-03-24T13:32:05Z",
    "updated_at": "2023-03-27T13:46:22Z",
    "permissions": {
        "ask_remote_unmute": false,
        "broadcast": false,
        "end_session": false,
        "general_chat": false,
        "manage_broadcast": false,
        "manage_roles": false,
        "manage_screenshare": false,
        "raise_hand": true,
        "recording": false,
        "remote_muting": [
            "speaker",
            "attendee"
        ],
        "remove_participant": false,
        "screenshare": false,
        "start_session": true
    }
}