API-Überblick
Die BigBlueButton-API ist eine HTTP-basierte Schnittstelle, die es externen Anwendungen — wie Lernmanagementsystemen, Webportalen und benutzerdefinierten Integrationen — ermöglicht, Meetings programmgesteuert zu erstellen, zu steuern und zu überwachen. Alle API-Aufrufe werden mit einem checksum-Mechanismus gesichert, der auf einem shared secret basiert.
Wie die API funktioniert
Die BBB-API folgt einem einfachen Request-Response-Modell. Sie senden eine HTTPS-Anfrage an einen bestimmten Endpunkt auf Ihrem BigBlueButton-Server, und der Server antwortet mit einem XML-Dokument, das Erfolg oder Fehler anzeigt.
- Protokoll: HTTPS (GET oder POST)
- Basis-URL:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Antwortformat: XML (mit wenigen Ausnahmen, die JSON zurückgeben)
- Authentifizierung: Shared-secret-basierte checksum (kein OAuth, kein API-Schlüssel)
Endpunkt-Kategorien
Die API-Endpunkte sind in die folgenden Kategorien gegliedert:
| Kategorie | Endpunkte | Beschreibung |
|---|---|---|
| Verwaltung | create, join, end | Meetings erstellen, beitreten und beenden |
| Ueberwachung | isMeetingRunning, getMeetings, getMeetingInfo | Laufende Meetings überwachen |
| Aufzeichnungen | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Meeting-Aufzeichnungen verwalten |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Echtzeit-Ereignisbenachrichtigungen |
| Nachrichten | sendChatMessage | Chat-Nachrichten senden BBB 3.0+ |
| Sitzung | getJoinUrl | Sitzungsverwaltung BBB 3.0+ |
HTTP Methoden
Die meisten Endpunkte akzeptieren sowohl GET- als auch POST-Anfragen. Bei Verwendung von POST beachten Sie, dass die checksum aus der URL-query string berechnet wird, nicht aus dem Request-Body. Der POST-Body kann zusätzliche Daten wie Präsentations-XML oder Client-Settings-Overrides enthalten.
Auch beim Senden einer POST-Anfrage muss die checksum aus den query string-Parametern in der URL berechnet werden. Der Body-Inhalt wird nicht in die checksum-Berechnung einbezogen.
Antwortformat
Jede API-Antwort enthält mindestens die folgenden Felder:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response> | Feld | Beschreibung |
|---|---|
returncode | Immer SUCCESS oder FAILED |
messageKey | Maschinenlesbarer Meldungscode (bei Fehlern und Warnungen sowie bei einigen erfolgreichen Antworten wie noMeetings oder sentEndMeetingRequest vorhanden) |
message | Menschenlesbare Beschreibung des Fehlers oder der Warnung |
API-Versionierung
Die BigBlueButton-API verwendet keine traditionelle URL-basierte Versionierung (keine Pfade wie /v1/, /v2/). Stattdessen werden neue Parameter abwärtskompatibel hinzugefügt, und veraltete Parameter werden entsprechend gekennzeichnet, aber nicht sofort entfernt.
| BBB Version | Wichtige API-Änderungen |
|---|---|
| 2.2 | Lock Einstellungen, allowModsToUnmuteUsers |
| 2.4 | meetingLayout, allowModsToEjectCameras, role (join), Lern-Dashboard |
| 2.5 | disabledFeatures, SHA-384/SHA-512-Unterstützung, webhook eventID Filter |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, Seitennavigation für Aufzeichnungen, Dunkelmodus |
| 2.7 | preUploadedPresentation (einzelne URL) |
| 3.0 | sendChatMessage, getJoinUrl, pluginManifests, clientSettingsOverride |
| 4.0 | lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, LiveKit als Standard-Medienbrücke, UNIFIED_LAYOUT als Standardlayout, Entfernung von Etherpad und mehreren veralteten Parametern – Von 3.x auf 4.x migrieren |
BigBlueButton 4.0 ist eine Ausnahme von dieser Regel: Mehrere Parameter und Layoutwerte, die als veraltet markiert waren oder keine Wirkung hatten, werden entfernt. Unbekannte Parameter werden weiterhin ignoriert, aber entfernte Aufzählungswerte (z. B. Layouts) und geänderte Standardwerte können das Verhalten bestehender Integrationen verändern.
Nicht dokumentierte Endpunkte
Die folgenden Endpunkte existieren im BigBlueButton-Quellcode, gehören aber nicht zur Integrations-API. Die offizielle Dokumentation beschreibt stuns, signOut und learningDashboard ausschließlich als interne Endpunkte des HTML5-Clients, die mit einem sessionToken statt einer Prüfsumme authentifiziert werden; getSessions ist überhaupt nicht dokumentiert. Sie können sich ohne Vorankündigung ändern.
| Endpunkt | Methode | Beschreibung | Status |
|---|---|---|---|
/api/stuns | GET POST | Gibt die STUN/TURN-Serverkonfiguration für WebRTC-Verbindungen zurück | Internal |
/api/signOut | GET POST | Sitzung beenden / Benutzer abmelden | Internal |
/api/getSessions | GET POST | Sitzungsinformationen abrufen | Undocumented |
/api/learningDashboard | GET POST | Lernanalyse-Daten abrufen | Internal |
GraphQL Mutations (Aktionen im Meeting)
Seit BBB 3.0 werden die meisten Echtzeitaktionen innerhalb eines Meetings über GraphQL-Mutations über WebSocket abgewickelt. Diese werden intern vom BBB-HTML5-Client verwendet und sind nicht Teil der klassischen REST-API.
| Kategorie | Anzahl | Beispiele |
|---|---|---|
| Chat | 12 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Benutzerverwaltung | 30 | userSetMuted, userSetRole, userEjectFromMeeting |
| Präsentation | 10 | presentationSetCurrent, presentationSetPage |
| Meeting-Steuerung | 8 | meetingEnd, meetingRecordingSetStatus |
| Gruppenräume | 8 | breakoutRoomCreate, breakoutRoomEndAll |
| Umfragen | 5 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Timer | 8 | timerStart, timerStop, timerReset |
| Plugins | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
Die GraphQL-Schicht ist für die interne Nutzung durch den Client gedacht und bietet keine stabile öffentliche API. Mutations und ihre Parameter können sich zwischen BBB-Versionen ohne Vorankündigung ändern.
Voraussetzungen
Bevor Sie die BigBlueButton-API nutzen können, stellen Sie sicher, dass Folgendes vorhanden ist:
Ein laufender BigBlueButton-Server (Version 4.0 empfohlen)
Das Shared Secret (auch "security salt" genannt), konfiguriert in /etc/bigbluebutton/bbb-web.properties
HTTPS-Zugriff auf den Server
Eine serverseitige Anwendung, die die API-Aufrufe erzeugt — das shared secret darf niemals clientseitig offengelegt werden
Legen Sie das shared secret niemals in clientseitigem Code offen (JavaScript, mobile Apps). Alle API-Aufrufe müssen serverseitig erzeugt werden, um unbefugten Zugriff auf Ihren BigBlueButton-Server zu verhindern.
Wenn Sie bbbserver.de verwenden, lesen Sie das spezielle Kapitel bbbserver.de IntegrationAPI zur Einrichtung des Dashboards, zur Plugin-Kompatibilität und zu den Unterschieden zur Standard-API.