How to Use Custom Roles in Digital Samba Developer API

Want to customise control over your online meetings? Digital Samba lets you make specific roles that give permissions to your webinar's hosts, speakers and guests. This guide shows how to use Digital Samba's developer API to build and handle custom roles that fit your unique moderation needs. It includes code samples to create, edit, list and remove roles. Why the wait? Let’s get started!

1. What are custom roles?
2. Benefits of custom roles
3. Using and managing custom roles in Digital Samba's API
4. Creating roles
5. Editing existing roles
6. List existing roles
7. Deleting existing role

What are custom roles?

Well-run online video conferencing events need clear rules. Digital Samba's API gives handy predefined Attendee, Speaker and Moderator roles. But some events need custom role settings. Custom roles let you tailor control to shape perfect experiences.

A role allows certain actions through permissions like sharing screens, recording, muting others and more. Blend permissions into custom roles matching your needs. Give assistants some Host powers, but not all. Stop speakers from removing guests. Digital Samba offers so many options for easy customisation!

For example, a "Moderator" role would have permissions like removing participants or starting/stopping recordings. An "Attendee" role may only have permissions for watching and chatting.

Here are some of the main permissions that can be configured:

• broadcast: Use microphone and camera
• manage_broadcast: Give/revoke broadcast permission
• remove_participant: Kick out participants
• screenshare: Share screen
• manage_screenshare: Allow others to screen share
• recording: Start/stop recordings
• general_chat: Chat openly
• remote_muting: Mute others' mics/cams
• raise_hand: Raise hand to grab the attention of others
• manage_roles: Move users between roles
• control_room_entry: Admit/deny waiting participants
• see_participants_panel: View the participant list
• invite_participant: Invite others to join

Some permissions apply globally, while others are role-sensitive. Role-sensitive permissions only allow the action on certain target roles.

For instance, you may want Speakers to be able to mute Attendees, but not Moderators. The remote_muting permission supports this by specifying which roles can be muted.

Benefits of custom roles

Custom roles offer significant advantages for managing online events and meetings. Rather than relying on generic default options, custom roles allow organisers to define specific privileges and restrictions for speakers and attendees that best suit their particular needs.

Here are some key benefits of using custom roles:

Although creating personalised roles requires some effort, it provides enhanced oversight, suitability, foresight and flexibility compared to out-of-the-box options. Custom roles empower organisers to produce events that truly match their desired participant outcomes.

Using and managing custom roles in Digital Samba's API

We have so far understood what roles are and the ones supported in the Digital Samba Developer API, in this section, we’ll learn how to create, edit, list, and delete roles that we are no longer using. That being said, let’s jump right in.

Creating roles

To create a new role, send a POST request to the /roles endpoint.

Include these fields:

• name - Unique internal name to reference the role in rooms and tokens
• display_name - Name people will see in the participant list
• permissions - JSON object with the allowed permissions (true) or not allowed (false). For permissions like remote_muting, you can specify which roles this role can mute. For example, let a Speaker mute Attendees but not Moderators. If you just put true, the role can operate on all current and future roles.
• description (optional) - Explanation of the role

Here’s a sample POST request for role creation:

Response (200 OK)

Note: Creating a role does not assign it to rooms automatically. To add a role to your room, please refer to Creating a room / General settings. If all rooms use the same roles, it is easier to set default roles in team settings. Then all rooms will inherit them.

Editing existing roles

To edit an existing role, make a PATCH request to /roles/:idOrName. You can use either the role's ID or name in the URL path. You can find the ID and name in the response when creating a role.

You can update as many fields as you want. 

Contact our team today!

Control the embedded video conference with the Digital Samba API

Contact our team today!

This example changes the display name and removes general chat permissions:

The response contains the updated role with the changes applied.

List existing roles

To see your existing roles, send a GET request to the /roles endpoint. Since there could be many roles, pagination is supported using limit, order, and after parameters. Read the pagination docs to learn more. By default, the maximum number of roles returned is 100.

Example request (list all roles):

Example response (200 OK):

Note: The total_count is the total number of roles globally, not just the number of roles returned in the data array for that page. For example, if there are 126 total roles but a limit of returning 100 per page, the total_count would show 126 but the data array would only contain 100 roles.

Example request (get one role's details):

Example response (200 OK):

Deleting existing role

To delete an existing role, send a DELETE request to the /roles/:idOrName endpoint. Using the role name is more human-readable than the ID, but you can use either the name or ID in the request.

Note: Role deletion is a destructive operation which cannot be undone. Also, note that you are not allowed to delete roles that are currently being used in a live session. Additionally, you cannot delete roles that are set as default roles in rooms.

Example request (deletes role 2d9448b9-d9ee-4102-b31a-f83ab4af2af8)

Response (204 -> No Content) 

The response body is empty because the role was deleted successfully and there is no content to return.

Conclusion

The Digital Samba Developer API gives you the power to customise user roles for tailored experiences. By setting specific permissions and assigning these custom roles correctly, you can build unique video chat solutions to meet your needs. With some thoughtful design around roles, you can transform your Digital Samba sessions into helpful, clear spaces for your team. The customisation options are flexible; use them to boost your platform and make it work for you.