Sie sehen die API-Dokumentation für BigBlueButton 3.x. Die aktuelle Version ist BigBlueButton 4.x. Planen Sie ein Upgrade? Der Migrationsleitfaden listet alle erforderlichen Änderungen an Ihren API-Aufrufen auf.
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 |
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 | 11 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Benutzerverwaltung | 28 | userSetMuted, userSetRole, userEjectFromMeeting |
| Präsentation | 10 | presentationSetCurrent, presentationSetPage |
| Meeting-Steuerung | 8 | meetingEnd, meetingRecordingSetStatus |
| Gruppenräume | 7 | 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 3.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.