Configuring your Digital Samba rooms with the developer API and SDK
Digital Samba Embedded lets you add fully featured video conferencing rooms to your own web application. You configure those rooms in two ways: the REST API manages rooms and their settings from your backend, while the JavaScript SDK embeds the room in your page and controls it during the call. Each room comes with features like screen sharing, chat, recording and a whiteboard, so most of the work is deciding what to switch on rather than building anything yourself.
In this guide, we'll walk through how to configure Digital Samba rooms with both tools: creating a room over the API, embedding it with the SDK, changing room settings with a PATCH request, and controlling the live call from your own interface.
Table of contents
- What you'll need
- How to configure your Digital Samba room using the API
- How to configure your Digital Samba room using the SDK
- Frequently asked questions
What you'll need
Before you configure anything, you need three things in place: a Digital Samba account with API credentials, a room, and the SDK embedded in your application.
1. A Digital Samba account and your API credentials
Every request to the REST API is authenticated with your team ID and developer key, sent in a standard HTTP Authorization header. Both values live in the dashboard's Team section, as shown below. The developer key never expires, and you can regenerate it from the same screen if it is ever exposed.

You can create a free account here if you need to sign up.
Important: never expose your developer key in the browser. Execute API requests only from your backend. The header value is the Base64 encoding of teamId:developerKey, and the API accepts it with both the Basic scheme – which is what curl's --user flag builds for you – and Bearer. Every major language has a built-in Base64 function.
2. A video conferencing room
Next, you need a room. You can create one in the dashboard or over the REST API. We'll use the API here; if you'd rather click through the interface, see our guide to configuring Digital Samba rooms using the dashboard.
To create a room, send a POST request to the /rooms endpoint. The only required field is privacy, which accepts public or private. Public rooms are open to anyone who knows the URL; private rooms require a valid token to enter. For moderated meetings, add the roles field – your team comes with moderator, speaker and attendee roles by default – and set a default_role whenever a room has more than one role. The create room documentation covers all the options, including the e2ee_enabled flag for end-to-end encryption.
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"
}'
If you'd rather take the JavaScript route, the same request from a Node.js backend looks like this:
const TEAM_ID = process.env.DS_TEAM_ID;
const DEVELOPER_KEY = process.env.DS_DEVELOPER_KEY;
const auth = Buffer.from(`${TEAM_ID}:${DEVELOPER_KEY}`).toString('base64');
const response = await fetch('https://api.digitalsamba.com/api/v1/rooms', {
method: 'POST',
headers: {
'Authorization': `Bearer ${auth}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
privacy: 'public',
roles: ['moderator', 'speaker', 'attendee'],
default_role: 'attendee'
})
});
const room = await response.json();
console.log(room.id, room.friendly_url);
The API responds with the room's id, a friendly_url, the privacy setting and the roles you assigned. If you don't provide a friendly URL yourself, the API auto-generates one, and your room becomes available at https://YOUR_TEAM.digitalsamba.com/FRIENDLY_URL. The default role is what participants get when they join a public room without a token, so it should normally be your least powerful role.
3. The SDK embedded in your application
With the room created, you embed it using the Digital Samba SDK, distributed as the npm module @digitalsamba/embedded-sdk. The SDK is written in TypeScript, so type definitions ship with it. Install it with npm install @digitalsamba/embedded-sdk, then:
- Import the DigitalSambaEmbedded class from the package.
- Call the createControl factory method with your initOptions – the room URL (or a team plus room pair), an optional root element the iframe should be created in, and an optional token for private rooms. If you don't pass a root element, the SDK appends the frame to the page body; it can also attach to an iframe you've already placed yourself.
- Call load() to load the room into the frame.
import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';
const sambaFrame = DigitalSambaEmbedded.createControl({
url: 'https://YOUR_TEAM.digitalsamba.com/YOUR_ROOM',
root: document.querySelector('#meeting-container')
// token: 'JWT_TOKEN_HERE' – required for private rooms
});
sambaFrame.load();
The load method accepts optional instanceProperties, where you can set iframe attributes and turn on error reporting to the browser console with reportErrors: true. The DigitalSambaEmbedded class documentation lists every valid initialisation combination.
With all three pieces in place, let's configure the room – first from the backend, then from the browser.
How to configure your Digital Samba room using the API
The API controls the room's persistent settings: anything you change here is stored on the room and applies to every session until you change it again. To edit an existing room, send a PATCH request to the /rooms/:id endpoint, using the room id (or friendly URL) from the create response.
Say you're running virtual lectures. You might enable screen sharing so the lecturer can present slides, keep chat on so students can ask questions without interrupting, and have cameras and microphones start switched off as students join, to cut down on noise and distractions:
curl --request PATCH \
--header "Content-Type: application/json" \
--url https://api.digitalsamba.com/api/v1/rooms/YOUR_ROOM_ID \
--user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
--data '{
"screenshare_enabled": true,
"chat_enabled": true,
"audio_on_join_enabled": false,
"video_on_join_enabled": false
}'
The same request in a Node.js backend:
const response = await fetch(`https://api.digitalsamba.com/api/v1/rooms/${roomId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${auth}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
screenshare_enabled: true,
chat_enabled: true,
audio_on_join_enabled: false,
video_on_join_enabled: false
})
});
You can update as many fields as you wish in one request – functionality toggles, branding colours like primary_color and toolbar_color, language, recording behaviour and security options. The full list of room fields is in the API reference.
Keep two related endpoints in mind. Team-wide default room settings have their own endpoint and are edited the same way, so new rooms start with the configuration you want – we cover that in our guide to configuring team settings with the Digital Samba API. And if your application needs to react to what happens in rooms, you can subscribe to webhooks for room and session events instead of polling the API.
How to configure your Digital Samba room using the SDK
The SDK controls the room from the client side, in real time. It gives you methods to control the call, events you can subscribe to for everything happening inside the room, and properties that describe the running conference.
Set the initial experience with roomSettings
The roomSettings object in your initOptions configures how the room loads for that user: their display name, the layout mode, whether the toolbar is visible, which devices to use and whether the camera and microphone start enabled. You can also pass a virtual background – or supply your own collection of backgrounds for users to pick from:
const sambaFrame = DigitalSambaEmbedded.createControl({
url: roomUrl,
roomSettings: {
username: 'John Smith',
appLanguage: 'en',
layoutMode: 'auto',
showToolbar: true,
videoEnabled: false,
audioEnabled: false,
virtualBackground: { blur: 'balanced' }
}
});
sambaFrame.load();
Control the call while it runs
Once the room is loaded, SDK methods let you adjust it on the fly. changeLayoutMode('tiled' | 'auto') switches between the tiled layout and the automatic layout that enlarges the active speaker. changeBrandingOptions() changes the palette mode and the primary, toolbar and background colours to match your brand. changeToolbarPosition() moves the toolbar to the left, bottom or right, and hideToolbar() / showToolbar() remove or restore it entirely – useful when you want your own interface to do the talking.
For moderated scenarios, the SDK really earns its keep. Suppose you've embedded Digital Samba in a telehealth or webinar application and want your own participants panel, where a moderator decides who can speak and who can share their screen:
// Let a participant broadcast – audio only, or audio and video
sambaFrame.allowBroadcast({ id: participantId, audio: true, video: true });
// Take broadcast permission away again
sambaFrame.disallowBroadcast(participantId);
// Grant and revoke screen sharing
sambaFrame.allowScreenshare(participantId);
sambaFrame.disallowScreenshare(participantId);
// Ask a participant to mute – they see a confirmation prompt
sambaFrame.requestMute(participantId);
These methods take the participant's id, so only that user is affected. Note that allowBroadcast lets you grant audio and video separately – handy in webinars where some guests should speak but not appear on camera. For the full picture of how participant control works, including roles and the participant list, see our guide to selecting and switching participants in a Digital Samba video call.
Extend the room with custom tiles and events
The SDK also lets you place your own content inside the room. addCustomTile() adds a tile with HTML you define – a timer, an AI assistant, a live poll – at the first or last position in the tile grid, and sendMessageToCustomTile() passes data to it while the call runs. addTileAction() adds your own entries to the three-dots menu on participant tiles and invokes your callback when someone clicks them:
// Add a custom tile once the local user has joined
sambaFrame.on('userJoined', (event) => {
if (event.data.type === 'local') {
sambaFrame.addCustomTile({
name: 'Agenda',
html: '<div><h3>Today</h3><p>1. Demo 2. Q&A</p></div>',
position: 'last'
});
}
});
// Add a custom entry to every remote participant's tile menu
sambaFrame.addTileAction(
'sendEmail',
{ label: 'Send email', scope: 'remote' },
() => console.log('Send email clicked')
);
Almost everything that happens in the room emits an event you can subscribe to with on() – participants joining and leaving, roles changing, recordings starting, the layout mode switching – so your interface can respond to the call as it happens. The room UI itself stays Digital Samba's prebuilt interface; what the SDK gives you is control over it from your own application, plus the custom tiles to put your content on the stage. Features such as the whiteboard have their own methods and API fields too – see how to enable the whiteboard in Digital Samba via the API.
Frequently asked questions
Do I need both the API and the SDK to configure rooms?
No, but they solve different problems. The REST API manages rooms and persistent settings from your backend, while the SDK embeds the room and controls the live call in the browser. Most production integrations use the API to create and configure rooms and the SDK to embed and control them.
Which fields are required to create a room?
Only the privacy field, set to public or private. Everything else is optional: if you skip friendly_url, the API generates one, and if a room has more than one role you must also set default_role.
Can I use my developer key in the browser?
No. The developer key grants full control of your team, so API requests belong on your backend only. In the browser, use the SDK with a room URL, and issue tokens from your backend when participants need to join private rooms.
What's the difference between API room settings and SDK roomSettings?
API fields are stored on the room and apply to every session until you change them. The SDK's roomSettings object applies when the room loads in that user's frame – things like their username, language, layout mode and whether devices start enabled.
Can I configure rooms without writing code?
Yes. The room settings covered in this guide can also be changed in the Digital Samba dashboard, room by room or through team-wide defaults. Our guide to configuring rooms using the dashboard walks through it.
Ready to build with Digital Samba?
Create a free developer account and configure your first room in minutes – 10,000 participation minutes per month included.
Share this
You May Also Like
These Related Stories

Easy Steps to Integrate Video Call on Your Website

Configuring your team settings with the Digital Samba Developer API

