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.
Se stai utilizzando bbbserver.de, consulta il capitolo dedicato a bbbserver.de IntegrationAPI per la configurazione della dashboard, la compatibilità dei plugin e le differenze rispetto all'API standard.