So konfigurierst du Raumvorgaben mit der Digital Samba Entwickler-API

5 min read
Oktober 24, 2023

Standard-Raumeinstellungen sind die Vorlage, auf der jeder Raum in Digital Samba basiert. Statt Toolbar, Farben, Sprache und Komponenten Raum für Raum zu konfigurieren, legst du sie einmal auf Team-Ebene fest – mit einem einzigen PATCH-Request an die Entwickler-API – und jeder Raum, den du erstellst, erbt sie automatisch. In diesem Artikel erfährst du, wie die Raumvererbung funktioniert, wie du deine Standard-Raumeinstellungen über die API einsiehst und änderst und wie du sie für einzelne Räume überschreibst.

Inhaltsübersicht

  1. Die Vererbung von Raumeinstellungen in Digital Samba verstehen
  2. Deine aktuellen Standard-Raumeinstellungen anzeigen
  3. Wie du deine Raumvorgaben mit der Entwickler-API konfigurierst
  4. Wie du die Vorgaben für einzelne Räume überschreibst
  5. Häufig gestellte Fragen

Die Vererbung von Raumeinstellungen in Digital Samba verstehen

Digital Samba Embedded nutzt eine einfache Hierarchie: Einstellungen, die auf Team-Ebene konfiguriert sind (die Standard-Raumeinstellungen), werden automatisch an deine Räume vererbt, sofern du einen Raum nicht gezielt anders konfigurierst. Wenn du gar keine Vorgaben setzt, erben neue Räume die Werkseinstellungen.

Die Vererbungsregel funktioniert so:

  • Neue Räume erben die Standard-Raumeinstellungen bei ihrer Erstellung.
  • Bestehende Räume erben Änderungen an den Standard-Raumeinstellungen ebenfalls – aber Einstellungen, die du an einem Raum individuell angepasst hast, werden niemals überschrieben.

Ein Beispiel: Du erstellst einen Raum und lässt seine Primärfarbe unverändert. Ändert ein Team-Admin später die Primärfarbe in den Standardeinstellungen auf Grün, wird auch dein Raum grün. Hattest du die Primärfarbe des Raums dagegen schon auf Rot gesetzt, bleibt sie rot – egal, was die Vorgaben sagen.

Das spart Zeit und sorgt für ein einheitliches Erlebnis: Markenfarben, Sprache und aktivierte Komponenten liegen an einer Stelle, und einzelne Räume enthalten nur die Abweichungen. Du kannst dieselben Einstellungen auch visuell verwalten – hier zeigen wir dir, wie du deine Standard-Raumeinstellungen im Digital Samba Dashboard konfigurierst.

Bevor du API-Aufrufe ausführst, brauchst du deine Zugangsdaten: Requests werden mit deiner Team-ID und deinem Entwicklerschlüssel authentifiziert. Beide findest du im Dashboard unter der Option „Team“, wie unten dargestellt.

dashboards Team option - Digital Samba-1

Wichtig: Gib deinen Entwicklerschlüssel niemals an den Browser deiner Nutzer weiter. Führe diese Requests ausschließlich von deinem Backend (serverseitig) aus. Das --user-Flag in den Beispielen unten übernimmt die HTTP-Basic-Authentifizierung für dich. Baust du den Authorization-Header selbst, kodiere TEAM_ID:DEVELOPER_KEY mit Base64 – jede größere Programmiersprache bringt dafür eine eingebaute Funktion mit.

Deine aktuellen Standard-Raumeinstellungen anzeigen

Um zu sehen, was deine Räume aktuell erben, führe einen GET-Request an den Root-Endpunkt /api/v1 aus:

curl --request GET \
  --url https://api.digitalsamba.com/api/v1 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY

Die Antwort listet alle Standardeigenschaften deines Teams auf – hier ein gekürztes Beispiel:

{
  "id": "c4fa4435-1381-4fd4-8bef-38a25da7eee1",
  "domain": "myTeamNameHere",
  "topbar_enabled": true,
  "toolbar_enabled": true,
  "toolbar_position": "bottom",
  "toolbar_color": "#000000",
  "primary_color": "#3771E0",
  "background_color": "#000000",
  "palette_mode": "light",
  "language": "en",
  "audio_on_join_enabled": true,
  "video_on_join_enabled": true,
  "screenshare_enabled": true,
  "participants_list_enabled": true,
  "chat_enabled": true,
  "e2ee_enabled": false,
  "join_screen_enabled": true,
  "logo_enabled": false,
  "recordings_enabled": true,
  "virtual_backgrounds_enabled": true,
  "raise_hand_enabled": true,
  ....................
}

Das ist zugleich eine praktische Referenz für die exakten Feldnamen, die du setzen kannst – die vollständige Antwort findest du in der Dokumentation der Standard-Raumeinstellungen.

Wie du deine Raumvorgaben mit der Entwickler-API konfigurierst

Um deine Standard-Raumeinstellungen zu bearbeiten, führe einen PATCH-Request an denselben Root-Endpunkt /api/v1 aus. Du kannst beliebig viele Felder in einem Aufruf aktualisieren – dieses Beispiel färbt die Toolbar blau und schaltet den Chat für alle erbenden Räume aus:

curl --request PATCH \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"toolbar_color": "#0000ff", "chat_enabled": false}'

Die Antwort enthält deine aktualisierten Standardeinstellungen (200 OK).

Ein realistischeres Szenario: Du möchtest eine einheitliche Markenidentität für alle deine Videokonferenzen. Ein einziger PATCH-Request setzt eine rechts positionierte grüne Toolbar, Grün als Primärfarbe, einen weißen Hintergrund, dein Logo und eine deutschsprachige Benutzeroberfläche:

curl --request PATCH \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
    "topbar_enabled": true,
    "toolbar_position": "right",
    "toolbar_color": "#2E7D32",
    "primary_color": "#2E7D32",
    "background_color": "#FFFFFF",
    "logo_enabled": true,
    "language": "de"
  }'

Du kannst hier auch e2ee_enabled auf true setzen, um Ende-zu-Ende-Verschlüsselung zum Standard für alle erbenden Räume zu machen. Triff diese Entscheidung bewusst statt pauschal: Bei aktiver Ende-zu-Ende-Verschlüsselung stehen Funktionen, die serverseitigen Medienzugriff brauchen – Umfragen, Q&A, Untertitel, Transkription und serverseitige Aufzeichnung – im Raum nicht zur Verfügung.

Mit der Videokonferenz-API von Digital Samba kannst du so viele Felder für deine Standardräume aktualisieren, wie du möchtest. Eine detaillierte Liste der konfigurierbaren Felder findest du in unserer Dokumentation.

Wie du die Vorgaben für einzelne Räume überschreibst

Die Vorgaben sind die Vorlage, einzelne Räume enthalten die Ausnahmen. Für raumspezifische Werte hast du zwei Möglichkeiten:

Bei der Erstellung – stelle einen POST-Request an den Endpunkt /rooms und übergib die Einstellungen zusammen mit dem einzigen Pflichtfeld privacy (public oder private).

Nach der Erstellung – führe einen PATCH-Request an den Endpunkt /rooms/:id aus. Die ID des Raums findest du in der Antwort auf den Create-Request.

Hältst du zum Beispiel einen Vortrag oder eine Schulung ab, kannst du die Bildschirmfreigabe für diesen einen Raum ausschalten, während der Chat aktiv bleibt und die Benutzeroberfläche auf Deutsch läuft. Selbst wenn die Bildschirmfreigabe in deinen Standard-Raumeinstellungen aktiviert ist, bleibt sie für diesen Raum aus – dauerhaft, denn individuell angepasste Raumeinstellungen werden von den Vorgaben nie überschrieben:

curl --request PATCH \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms/c39d7c40-7ff7-4faa-b06f-698a639a9523 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
    "screenshare_enabled": false,
    "chat_enabled": true,
    "language": "de"
  }'

Für moderierte Meetings oder Webinare solltest du beim Erstellen eines Raums zusätzlich die Felder roles und default_role setzen – Details dazu findest du in der Dokumentation zu Rollen und Berechtigungen. Und wenn du tiefer in die Konfiguration einzelner Räume einsteigen willst, inklusive der vollständigen Liste der Raumfelder, lies unseren Guide zur Konfiguration deiner Digital Samba Räume mit Entwickler-API und SDK.

Häufig gestellte Fragen

Was sind Standard-Raumeinstellungen in Digital Samba?

Standard-Raumeinstellungen sind eine Vorlage auf Team-Ebene für deine Räume – von Branding über Sprache bis zu den Komponenten. Jeder Raum, den du erstellst, erbt sie automatisch, sodass du pro Raum nur die Ausnahmen konfigurierst. Bearbeiten kannst du sie über die Entwickler-API oder im Dashboard.

Wirken sich Änderungen an den Standardeinstellungen auf bestehende Räume aus?

Ja. Auch bestehende Räume erben Änderungen an den Standard-Raumeinstellungen – allerdings nur bei Einstellungen, die du am Raum selbst nicht angepasst hast. Ein Wert, den du direkt an einem Raum gesetzt hast, wird von den Vorgaben nie überschrieben.

Welche Einstellungen werden nicht von den Vorgaben vererbt?

Ob ein Raum öffentlich oder privat ist (Feld privacy), legst du pro Raum fest – es ist das einzige Pflichtfeld beim Erstellen eines Raums – und auch die maximale Teilnehmerzahl wird individuell konfiguriert. Alles andere, von Farben bis zu Komponenten, folgt den Standard-Raumeinstellungen, sofern du es nicht überschreibst.

Welcher Endpunkt aktualisiert die Standard-Raumeinstellungen?

Der Root-Endpunkt der REST-API: Sende einen PATCH-Request an https://api.digitalsamba.com/api/v1 mit den Feldern, die du ändern möchtest. Ein GET-Request an denselben Endpunkt liefert deine aktuellen Vorgaben zurück.

Kann ich meine Standard-Raumeinstellungen zurücksetzen?

Ja. Das Formular „Standard-Raumeinstellungen“ im Dashboard hat einen Button zum Zurücksetzen auf die Werkseinstellungen. Beachte: Änderungen oder Löschungen an den vordefinierten Rollen sind davon unabhängig und werden durch das Zurücksetzen nicht rückgängig gemacht.

Passe Videoanrufe in deiner Anwendung mit Digital Samba Embedded an

Die Raumvererbung nimmt dir die Arbeit ab: Setze deine Standard-Raumeinstellungen einmal über die Entwickler-API von Digital Samba Embedded, und jeder neue Raum startet gebrandet, konfiguriert und konsistent – während sich einzelne Räume weiterhin an die jeweilige Session anpassen lassen.

Starte noch heute mit einem kostenlosen Konto.