API-overzicht
De BigBlueButton-API is een interface op basis van HTTP waarmee externe applicaties — zoals learningmanagementsystemen, webportalen en aangepaste integraties — programmatisch vergaderingen kunnen aanmaken, beheren en monitoren. Alle API-aanroepen worden beveiligd met een checksum-mechanisme op basis van een shared secret.
Hoe de API werkt
De BBB-API volgt een eenvoudig request-response-model. Je stuurt een HTTPS-verzoek naar een specifiek endpoint op je BigBlueButton-server, en de server antwoordt met een XML-document dat succes of mislukking aangeeft.
- Protocol: HTTPS (GET of POST)
- Basis-URL:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Antwoordformaat: XML (met enkele uitzonderingen die JSON retourneren)
- Authenticatie: op Shared-secret gebaseerde checksum (geen OAuth, geen API-sleutel)
Endpointcategorieën
De API-endpoints zijn ingedeeld in de volgende categorieën:
| Categorie | Endpoints | Beschrijving |
|---|---|---|
| Beheer | create, join, end | Vergaderingen aanmaken, deelnemen en beëindigen |
| Monitoring | isMeetingRunning, getMeetings, getMeetingInfo | Actieve vergaderingen monitoren |
| Opnames | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Vergaderopnamen beheren |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Realtime gebeurtenismeldingen |
| Berichten | sendChatMessage | Chatberichten verzenden BBB 3.0+ |
| Sessie | getJoinUrl, feedback | Sessiebeheer BBB 3.0+ |
HTTP Methoden
De meeste endpoints accepteren zowel GET- als POST-verzoeken. Let er bij gebruik van POST op dat de checksum wordt berekend op basis van de URL-query string, niet op basis van de requestbody. De POST-body kan aanvullende gegevens bevatten zoals presentatie-XML of overrides voor clientinstellingen.
Zelfs bij het verzenden van een POST-verzoek moet de checksum worden berekend op basis van de query string-parameters in de URL. De inhoud van de body wordt niet meegenomen in de berekening van de checksum.
Responseformaat
Elke API-respons bevat ten minste de volgende velden:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response>| Veld | Beschrijving |
|---|---|
returncode | Altijd SUCCESS of FAILED |
messageKey | Machineleesbare foutcode (alleen aanwezig bij fouten of waarschuwingen) |
message | Menselijk leesbare beschrijving van de fout of waarschuwing |
API-versionering
De BigBlueButton-API gebruikt geen traditionele URL-gebaseerde versiebeheer (geen paden als /v1/, /v2/). In plaats daarvan worden nieuwe parameters op een achterwaarts compatibele manier toegevoegd, en verouderde parameters worden als zodanig gemarkeerd maar niet onmiddellijk verwijderd.
| BBB Versie | Opmerkelijke API-wijzigingen |
|---|---|
| 2.2 | Lock-instellingen, allowModsToUnmuteUsers |
| 2.4 | logo, meetingLayout, allowModsToEjectCameras, Leerdashboard |
| 2.5 | disabledFeatures, ondersteuning voor SHA-384/SHA-512, webhook eventID filter |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, donkere modus |
| 2.7 | preUploadedPresentation (enkele URL), opname-pagination |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role vervangt password op join |
Niet-gedocumenteerde endpoints
De volgende endpoints bestaan in de broncode van BigBlueButton, maar worden niet behandeld in de officiële documentatie. Ze worden intern gebruikt en kunnen zonder kennisgeving veranderen.
| Endpoint | Methode | Beschrijving | Status |
|---|---|---|---|
/api/stuns | GET POST | Retourneert de serverconfiguratie STUN/TURN voor WebRTC-verbindingen | Undocumented |
/api/signOut | GET POST | Sessie beëindigen / gebruiker afmelden | Undocumented |
/api/guestWait | GET | Lobbystatus opvragen voor gasten die wachten op goedkeuring door een moderator | Undocumented |
/api/getSessions | GET POST | Sessie-informatie ophalen | Undocumented |
/api/learningDashboard | GET POST | Gegevens voor leeranalyses ophalen | Undocumented |
GraphQL Mutaties (acties tijdens de vergadering)
Sinds BBB 3.0 worden de meeste realtime acties binnen een vergadering afgehandeld via GraphQL-mutaties over WebSocket. Deze worden intern gebruikt door de BBB HTML5-client en maken geen deel uit van de klassieke REST-API.
| Categorie | Aantal | Voorbeelden |
|---|---|---|
| Chat | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Gebruikersbeheer | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Presentatie | 11 | presentationSetCurrent, presentationSetPage |
| Vergaderbeheer | 8 | meetingEnd, meetingRecordingSetStatus |
| Breakoutruimtes | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Peilingen | 4 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Timer | 8 | timerStart, timerStop, timerReset |
| Plug-ins | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
De GraphQL-laag is bedoeld voor intern clientgebruik en biedt geen stabiele publieke API. Mutaties en hun parameters kunnen zonder kennisgeving tussen BBB-versies veranderen.
Vereisten
Voordat je de BigBlueButton-API kunt gaan gebruiken, moet je ervoor zorgen dat je over het volgende beschikt:
Een actieve BigBlueButton-server (versie 3.0 aanbevolen)
Het gedeelde geheim (ook wel "security salt" genoemd), geconfigureerd in /etc/bigbluebutton/bbb-web.properties
HTTPS-toegang tot de server
Een server-side applicatie die de API-aanroepen genereert — de shared secret mag nooit aan de clientzijde worden blootgesteld
Stel de shared secret nooit bloot in client-side code (JavaScript, mobiele apps). Alle API-aanroepen moeten server-side worden gegenereerd om ongeautoriseerde toegang tot je BigBlueButton-server te voorkomen.
Als je bbbserver.de gebruikt, raadpleeg dan het speciale hoofdstuk bbbserver.de IntegratieAPI voor dashboardinstellingen, plugincompatibiliteit en verschillen met de standaard-API.