Panoramica API
L'API BigBlueButton è un'interfaccia basata su HTTP che consente ad applicazioni esterne — come sistemi di gestione dell'apprendimento, portali web e integrazioni personalizzate — di creare, controllare e monitorare riunioni in modo programmatico. Tutte le chiamate API sono protette tramite un meccanismo checksum basato su un shared secret.
Come funziona l'API
L'API BBB segue un semplice modello richiesta-risposta. Invi un richiesta HTTPS a uno specifico endpoint sul tuo server BigBlueButton e il server risponde con un documento XML che indica successo o errore.
- Protocollo: HTTPS (GET o POST)
- URL di base:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Formato di risposta: XML (con poche eccezioni che restituiscono JSON)
- Autenticazione: Shared-secret basata su checksum (nessun OAuth, nessuna chiave API)
Categorie degli endpoint
Gli endpoint API sono organizzati nelle seguenti categorie:
| Categoria | Endpoint | Descrizione |
|---|---|---|
| Amministrazione | create, join, end | Creare, partecipare e terminare riunioni |
| Monitoraggio | isMeetingRunning, getMeetings, getMeetingInfo | Monitorare le riunioni in esecuzione |
| Registrazioni | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Gestire le registrazioni delle riunioni |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Notifiche di eventi in tempo reale |
| Messaggistica | sendChatMessage | Inviare messaggi in chat BBB 3.0+ |
| Sessione | getJoinUrl, feedback | Gestione della sessione BBB 3.0+ |
Metodi HTTP
La maggior parte degli endpoint accetta sia richieste GET sia POST. Quando usi POST, tieni presente che il checksum viene calcolato dalla query string dell'URL, non dal corpo della richiesta. Il corpo POST può contenere dati aggiuntivi come XML di presentazione o sovrascritture delle impostazioni client.
Anche quando invii una richiesta POST, il checksum deve essere calcolato dai parametri query string nell'URL. Il contenuto del corpo non è incluso nel calcolo del checksum.
Formato della risposta
Ogni risposta API contiene almeno i seguenti campi:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response>| Campo | Descrizione |
|---|---|
returncode | Sempre SUCCESS o FAILED |
messageKey | Codice di errore leggibile dalla macchina (presente solo in caso di errori o avvisi) |
message | Descrizione dell'errore o dell'avviso leggibile dall'uomo |
Versioning dell'API
L'API BigBlueButton non usa il tradizionale versionamento basato su URL (nessun percorso /v1/, /v2/). Invece, vengono aggiunti nuovi parametri in modo retrocompatibile e i parametri deprecati vengono contrassegnati di conseguenza ma non rimossi immediatamente.
| Versione BBB | Modifiche API rilevanti |
|---|---|
| 2.2 | impostazioni Lock, allowModsToUnmuteUsers |
| 2.4 | logo, meetingLayout, allowModsToEjectCameras, Dashboard di apprendimento |
| 2.5 | disabledFeatures, supporto SHA-384/SHA-512, webhook eventID filtro |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, modalità scura |
| 2.7 | preUploadedPresentation (URL singolo), registrazione pagination |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role sostituisce password su join |
Endpoint non documentati
I seguenti endpoint esistono nel codice sorgente BigBlueButton ma non sono trattati nella documentazione ufficiale. Sono usati internamente e possono cambiare senza preavviso.
| Endpoint | Metodo | Descrizione | Stato |
|---|---|---|---|
/api/stuns | GET POST | Restituisce la configurazione del server STUN/TURN per le connessioni WebRTC | Undocumented |
/api/signOut | GET POST | Termina la sessione / disconnette l'utente | Undocumented |
/api/guestWait | GET | Interroga lo stato della lobby per gli ospiti in attesa dell'approvazione del moderatore | Undocumented |
/api/getSessions | GET POST | Recupera informazioni sulla sessione | Undocumented |
/api/learningDashboard | GET POST | Recupera dati di learning analytics | Undocumented |
Mutazioni GraphQL (azioni in riunione)
Da BBB 3.0, la maggior parte delle azioni in tempo reale all'interno di una riunione viene gestita tramite mutazioni GraphQL su WebSocket. Queste sono usate internamente dal client HTML5 BBB e non fanno parte della classica API REST.
| Categoria | Conteggio | Esempi |
|---|---|---|
| Chat | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Gestione utenti | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Presentazione | 11 | presentationSetCurrent, presentationSetPage |
| Controllo della riunione | 8 | meetingEnd, meetingRecordingSetStatus |
| Stanze di sottogruppo | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Sondaggi | 4 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Timer | 8 | timerStart, timerStop, timerReset |
| Plugin | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
Il livello GraphQL è destinato all'uso interno del client e non fornisce un'API pubblica stabile. Le mutazioni e i loro parametri possono cambiare tra versioni BBB senza preavviso.
Prerequisiti
Prima di poter iniziare a usare l'API BigBlueButton, assicurati di avere quanto segue:
Un server BigBlueButton in esecuzione (versione 3.0 consigliata)
Il segreto condiviso (chiamato anche "security salt"), configurato in /etc/bigbluebutton/bbb-web.properties
Accesso HTTPS al server
Un'applicazione lato server che genera le chiamate API — il shared secret non deve mai essere esposto sul lato client
Non esporre mai il shared secret nel codice lato client (JavaScript, app mobili). Tutte le chiamate API devono essere generate lato server per prevenire accessi non autorizzati al tuo server BigBlueButton.
bbbserver.de — IntegrationAPI
bbbserver.de è una piattaforma di hosting premium basata nell'UE per BigBlueButton con server situati nell'UE. Il IntegrationAPI è un proxy che replica completamente l'API standard BBB — le applicazioni esterne si collegano tramite plugin BBB standard e si comportano come se stessero comunicando con un singolo server BBB. Dietro le quinte, bbbserver distribuisce automaticamente le conferenze su più server con capacità sufficiente.
Il tuo URL API e il shared secret sono disponibili nel pannello di amministrazione bbbserver in Customer Settings → IntegrationAPI. Il IntegrationAPI può essere abilitato o disabilitato da lì.
Compatibilità Plugin
Le seguenti piattaforme funzionano subito — basta inserire l'URL API e il shared secret:
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Differenze rispetto all'API standard
| Argomento | Dettaglio |
|---|---|
maxParticipants / duration | Utilizzato per la prenotazione della capacità, non solo come limite. Valori predefiniti se non specificati: 5 partecipanti, 60 minuti. |
duration comportamento | NON termina automaticamente le riunioni — utilizzato solo per la pianificazione della capacità. |
| Parametro aggiuntivo | deactivateBbbserverDefaultChatTexts — per finalità di white-labeling. |
| Endpoint non disponibili | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Solo specifico per riunione, con offuscamento della privacy. |
| Limiti di velocità | Nessun limite di frequenza sul IntegrationAPI. |
Oltre al IntegrationAPI, bbbserver.de offre un System API separato con funzionalità specifiche della piattaforma come gestione dell'account e statistiche di utilizzo. Il System API non è compatibile con BBB e non è trattato in questa guida.