API-Ueberblick
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, feedback | 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 Fehlercode (nur bei Fehlern oder Warnungen 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 | logo, meetingLayout, allowModsToEjectCameras, Lern-Dashboard |
| 2.5 | disabledFeatures, SHA-384/SHA-512-Unterstützung, webhook eventID Filter |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, Dunkelmodus |
| 2.7 | preUploadedPresentation (einzelne URL), Aufzeichnungs-pagination |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role ersetzt password auf join |
Nicht dokumentierte Endpunkte
Die folgenden Endpunkte existieren im BigBlueButton-Quellcode, sind aber nicht in der offiziellen Dokumentation enthalten. Sie werden intern verwendet und 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 | Undocumented |
/api/signOut | GET POST | Sitzung beenden / Benutzer abmelden | Undocumented |
/api/guestWait | GET | Lobby-Status für Gäste abfragen, die auf die Genehmigung durch einen Moderator warten | Undocumented |
/api/getSessions | GET POST | Sitzungsinformationen abrufen | Undocumented |
/api/learningDashboard | GET POST | Lernanalyse-Daten abrufen | Undocumented |
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 | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Benutzerverwaltung | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Präsentation | 11 | presentationSetCurrent, presentationSetPage |
| Meeting-Steuerung | 8 | meetingEnd, meetingRecordingSetStatus |
| Gruppenräume | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Umfragen | 4 | 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.
bbbserver.de — IntegrationAPI
bbbserver.de ist eine EU-basierte Premium-Hosting-Plattform für BigBlueButton mit Servern in der EU. Das IntegrationAPI ist ein Proxy, der die Standard-BBB-API vollständig repliziert — externe Anwendungen verbinden sich über Standard-BBB-Plugins und verhalten sich so, als würden sie mit einem einzelnen BBB-Server kommunizieren. Im Hintergrund verteilt bbbserver Konferenzen automatisch auf mehrere Server mit ausreichender Kapazität.
Ihre API-URL und das shared secret sind im bbbserver-Admin-Panel unter Customer Settings → IntegrationAPI verfügbar. Das IntegrationAPI kann dort aktiviert oder deaktiviert werden.
Plugin Kompatibilität
Die folgenden Plattformen funktionieren sofort — geben Sie einfach die API-URL und das shared secret ein:
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Unterschiede zur Standard-API
| Thema | Detail |
|---|---|
maxParticipants / duration | Wird zur Kapazitätsreservierung verwendet, nicht nur als Begrenzung. Standardwerte, wenn nicht angegeben: 5 Teilnehmer, 60 Minuten. |
duration Verhalten | Beendet Meetings NICHT automatisch — wird nur für die Kapazitätsplanung verwendet. |
| Zusätzlicher Parameter | deactivateBbbserverDefaultChatTexts — für white-labeling-Zwecke. |
| Nicht verfügbare Endpunkte | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Nur meetingspezifisch, mit Datenschutz-Verschleierung. |
| Ratenbegrenzungen | Keine Rate Limits auf der IntegrationAPI. |
Zusätzlich zur IntegrationAPI bietet bbbserver.de eine separate System API mit plattformspezifischen Funktionen wie Kontoverwaltung und Nutzungsstatistiken. Die System API ist nicht BBB-kompatibel und wird in diesem Leitfaden nicht behandelt.