API-Version: 4.x neueste 3.x

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.

Kapitel 1

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.

Häufig gestellte Fragen

Die API verwendet einen shared-secret-basierten checksum-Mechanismus. Jede Anfrage muss einen Parameter checksum enthalten, der durch Hashing des API-Aufrufnamens, des query string und des shared secret berechnet wird. Es gibt keine OAuth- oder API-Schlüssel-Authentifizierung.

Das Standard-Antwortformat ist XML. Einige wenige spezifische Endpunkte können JSON zurückgeben, aber die große Mehrheit der API-Aufrufe gibt XML-Dokumente mit einem Feld returncode zurück, das SUCCESS oder FAILED anzeigt.

Nein, die BigBlueButton-API verwendet keine URL-basierte Versionierung. Neue Parameter werden auf abwärtskompatible Weise hinzugefügt, und veraltete Parameter werden gekennzeichnet, aber nicht sofort entfernt. Sie sollten immer das Changelog für Ihre BBB-Version prüfen.

Nein. Die GraphQL-Schicht ist für die interne Nutzung durch den BBB-HTML5-Client konzipiert. Sie bietet keine stabile öffentliche API, und Mutations können sich zwischen Versionen ohne Vorankündigung ändern. Verwenden Sie für alle externen Integrationen die REST-API.

BigBlueButton 3.0 akzeptiert standardmäßig SHA-1, SHA-256, SHA-384 und SHA-512 für die Berechnung von checksum (konfigurierbar über supportedChecksumAlgorithms). SHA-384 und SHA-512 wurden in BigBlueButton 2.5.8 hinzugefügt; ältere Versionen akzeptieren nur SHA-1 und SHA-256. Aus Sicherheitsgründen wird empfohlen, SHA-256 oder höher zu verwenden.