Hoofdstuk 1

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.

bbbserver.de — IntegrationAPI

Je API-URL en shared secret zijn beschikbaar in het bbbserver-beheerpaneel onder Customer Settings → IntegrationAPI. De IntegrationAPI kan daar worden in- of uitgeschakeld.

Plugin Compatibiliteit

De volgende platforms werken direct — voer simpelweg de API-URL en shared secret in:

  • Moodle (BigBlueButtonBN)
  • ILIAS
  • Nextcloud
  • WordPress
  • Greenlight

Verschillen met de standaard-API

Onderwerp Detail
maxParticipants / duration Wordt gebruikt voor capaciteitsreservering, niet alleen als limieten. Standaardwaarden indien niet opgegeven: 5 deelnemers, 60 minuten.
duration gedrag Beëindigt vergaderingen NIET automatisch — wordt alleen gebruikt voor capaciteitsplanning.
Extra parameter deactivateBbbserverDefaultChatTexts — voor white-labeling-doeleinden.
Niet-beschikbare eindpunten updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks
Webhooks Alleen vergaderspecifiek, met privacyverhulling.
Snelheidslimieten Geen rate limits op de IntegrationAPI.

Naast de IntegrationAPI biedt bbbserver.de een afzonderlijke System API met platformspecifieke functies zoals accountbeheer en gebruiksstatistieken. De System API is niet compatibel met BBB en wordt niet behandeld in deze handleiding.

Veelgestelde vragen

De API gebruikt een op shared-secret gebaseerde checksum-mechanisme. Elk verzoek moet een parameter checksum bevatten die wordt berekend door de naam van de API-aanroep, de query string en de shared secret te hashen. Er is geen OAuth- of API-sleutelauthenticatie.

Het standaard antwoordformaat is XML. Enkele specifieke endpoints kunnen JSON retourneren, maar het overgrote deel van de API-aanroepen retourneert XML-documenten met een veld returncode dat SUCCESS of FAILED aangeeft.

Nee, de BigBlueButton-API gebruikt geen URL-gebaseerde versiebeheer. Nieuwe parameters worden op een achterwaarts compatibele manier toegevoegd, en verouderde parameters worden gemarkeerd maar niet onmiddellijk verwijderd. Controleer altijd de changelog voor jouw BBB-versie.

Nee. De GraphQL-laag is ontworpen voor intern gebruik door de BBB HTML5-client. Deze biedt geen stabiele publieke API, en mutaties kunnen zonder kennisgeving tussen versies veranderen. Gebruik de REST-API voor alle externe integraties.

De bbbserver.de IntegrationAPI is een proxy die de standaard BBB-API volledig repliceert. Externe applicaties verbinden ermee alsof ze met één enkele BBB-server communiceren. De belangrijkste verschillen zijn capaciteitsreservering via maxParticipants/duration, enkele niet-beschikbare endpoints en vergaderingsspecifieke webhook-beperkingen.

BigBlueButton 2.5 en later ondersteunt SHA-256, SHA-384 en SHA-512 voor de berekening van checksum. Eerdere versies gebruiken SHA-1 of SHA-256. Om veiligheidsredenen wordt aanbevolen SHA-256 of hoger te gebruiken.