Stai visualizzando la documentazione API per BigBlueButton 3.x. La versione attuale è BigBlueButton 4.x. Stai pianificando un aggiornamento? La guida alla migrazione elenca tutte le modifiche necessarie alle tue chiamate API.
getMeetingInfo – Ottieni dettagli della riunione
L'endpoint getMeetingInfo restituisce informazioni dettagliate su una singola riunione BigBlueButton, inclusi i partecipanti attuali, i metadati, le impostazioni di configurazione e lo stato della registrazione. Usalo per ispezionare una specifica riunione in tempo reale.
Endpoint
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?<parameter>&checksum=replace-with-checksum Questo endpoint richiede un checksum valido calcolato dal segreto condiviso del tuo server BigBlueButton. Sono supportate sia richieste GET sia POST.
Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
meetingID | String | Sì | L'identificatore della riunione da interrogare. Questo è l'ID che hai specificato quando la riunione è stata creata. |
Campi della risposta
Una risposta riuscita contiene i seguenti campi che descrivono la riunione e il suo stato attuale:
| Campo | Tipo | Descrizione |
|---|---|---|
returncode | String | Indica se la chiamata è riuscita. Restituisce SUCCESS o FAILED. |
meetingName | String | Il nome della riunione leggibile dall'uomo. |
meetingID | String | L'identificatore esterno della riunione come specificato durante la creazione. |
internalMeetingID | String | L'identificatore univoco interno generato da BigBlueButton. |
createTime | Long | Timestamp (in millisecondi dall'epoch) di quando è stata creata la riunione. |
createDate | String | Data e ora leggibili dall'uomo di quando è stata creata la riunione. |
voiceBridge | String | Il numero del voice bridge per l'accesso telefonico. |
dialNumber | String | Il numero di telefono per l'accesso tramite chiamata, se configurato. |
attendeePW | String deprecated | La password del partecipante. Inclusa per compatibilità con le versioni precedenti ma deprecata da BigBlueButton 2.5. |
moderatorPW | String deprecated | La password del moderatore. Inclusa per compatibilità con le versioni precedenti ma deprecata da BigBlueButton 2.5. |
running | Boolean | Se la riunione è attualmente in esecuzione (true) o meno (false). |
duration | Integer | La durata massima della riunione in minuti. Un valore di 0 significa illimitata. |
hasUserJoined | Boolean | Indica se almeno un utente ha partecipato alla riunione. |
recording | Boolean | Indica se la registrazione è abilitata per questa riunione. |
hasBeenForciblyEnded | Boolean | Impostato su true al termine della riunione, indipendentemente da come è stata terminata. Poiché BigBlueButton rimuove immediatamente dalla memoria una riunione terminata, le risposte contengono praticamente sempre false. |
startTime | Long | Timestamp (in millisecondi) di quando è iniziata la riunione. |
endTime | Long | Timestamp (in millisecondi) di quando è terminata la riunione. Restituisce 0 se è ancora in esecuzione. |
participantCount | Integer | Il numero totale di partecipanti attualmente presenti nella riunione. |
listenerCount | Integer | Il numero di partecipanti in modalità solo ascolto. |
voiceParticipantCount | Integer | Il numero di partecipanti che hanno effettuato l'accesso al canale audio. |
videoCount | Integer | Il numero di flussi video delle webcam attualmente condivisi nella riunione. |
maxUsers | Integer | Il numero massimo di utenti consentiti. Un valore di 0 significa illimitato. |
moderatorCount | Integer | Il numero di moderatori attualmente presenti nella riunione. |
attendees | XML Container | Contiene un elenco di elementi attendee con dettagli su ciascun partecipante connesso (vedi Campi attendee qui sotto). |
metadata | XML Container | Contiene le coppie chiave-valore dei metadati personalizzati passati durante la creazione della riunione. |
isBreakout | Boolean | Indica se la riunione è una breakout room. |
parentMeetingID | String | L'ID interno della riunione (internalMeetingID) della riunione principale. Presente solo per le stanze per gruppi di lavoro. |
sequence | Integer | Il numero di sequenza della breakout room. Presente solo per le breakout room. |
freeJoin | Boolean | Indica se i partecipanti possono scegliere liberamente a quale breakout room unirsi. Presente solo per le breakout room. |
breakoutRooms | XML Container | Elenca gli ID delle stanze di gruppo associati a questa riunione. Presente solo quando sono state create stanze di gruppo. |
Campi dei partecipanti
Ogni elemento attendee all'interno di attendees contiene i seguenti campi:
| Campo | Tipo | Descrizione |
|---|---|---|
userID | String | L'ID utente esterno passato come userID a join. Se non ne è stato passato alcuno, viene restituito l'ID utente interno generato da BigBlueButton (formato w_xxxxxxxxxxxx). |
fullName | String | Il nome visualizzato del partecipante. |
role | Enum | Il ruolo del partecipante: MODERATOR o VIEWER. Gli utenti che accedono telefonicamente sono elencati con DIAL-IN-USER. |
isPresenter | Boolean | Indica se il partecipante è attualmente il presentatore. |
isListeningOnly | Boolean | Se il partecipante è in modalità solo ascolto. |
hasJoinedVoice | Boolean | Se il partecipante ha effettuato l'accesso al canale audio con un microfono. |
hasVideo | Boolean | Se il partecipante sta condividendo la propria webcam. |
clientType | String | Il tipo di client che il partecipante sta usando. Tipicamente HTML5. |
customdata | XML Container | Contiene i parametri userdata-* passati a join sotto forma di elementi figlio XML (senza prefisso). Presente per ogni partecipante che si è unito tramite join; vuoto se non sono stati passati parametri di questo tipo. |
Esempio di richiesta
GET https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?meetingID=replace-with-meeting-id&checksum=replace-with-checksum Esempio di risposta (successo)
<response>
<returncode>SUCCESS</returncode>
<meetingName>Project Discussion</meetingName>
<meetingID>replace-with-meeting-id</meetingID>
<internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
<createTime>1715261728123</createTime>
<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
<voiceBridge>66052</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<attendeePW>replace-with-password</attendeePW>
<moderatorPW>replace-with-password</moderatorPW>
<running>true</running>
<duration>0</duration>
<hasUserJoined>true</hasUserJoined>
<recording>true</recording>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<startTime>1715261728142</startTime>
<endTime>0</endTime>
<participantCount>3</participantCount>
<listenerCount>1</listenerCount>
<voiceParticipantCount>2</voiceParticipantCount>
<videoCount>2</videoCount>
<maxUsers>0</maxUsers>
<moderatorCount>1</moderatorCount>
<attendees>
<attendee>
<userID>replace-with-user-id</userID>
<fullName>Max Mustermann</fullName>
<role>MODERATOR</role>
<isPresenter>true</isPresenter>
<isListeningOnly>false</isListeningOnly>
<hasJoinedVoice>true</hasJoinedVoice>
<hasVideo>true</hasVideo>
<clientType>HTML5</clientType>
<customdata></customdata>
</attendee>
</attendees>
<metadata>
<bbb-origin>greenlight</bbb-origin>
<bbb-origin-version>v3.1.0</bbb-origin-version>
<endcallbackurl>https://api-guide.bbbserver.com/callbacks/meeting-ended</endcallbackurl>
</metadata>
<isBreakout>false</isBreakout>
</response> Risposta di errore
Se l'ID riunione specificato non esiste o è già terminato, l'API restituisce una risposta FAILED:
<response>
<returncode>FAILED</returncode>
<messageKey>notFound</messageKey>
<message>A meeting with that ID does not exist</message>
</response> Un errore notFound non significa necessariamente che la riunione non sia mai stata creata. Potrebbe essere già terminata ed essere stata rimossa dalla memoria del server. BigBlueButton conserva i dati della riunione solo mentre la riunione è attiva.
getMeetingInfo vs. getMeetings
| Aspetto | getMeetings | getMeetingInfo |
|---|---|---|
| Ambito | Tutte le riunioni attive sul server | Una singola riunione specifica |
| Parametri | Nessuno richiesto | meetingID obbligatorio |
| Dettagli dei partecipanti | Utenti connessi e utenti che hanno abbandonato la riunione di recente (rimossi dopo 60 secondi per impostazione predefinita) | Solo gli utenti attualmente connessi |
| Caso d'uso | Panoramica della dashboard e del monitoraggio | Ispezione mirata di una riunione specifica |
Casi d’uso comuni
- Logica di accesso — verifica se è presente un moderatore prima di reindirizzare gli ospiti nella riunione.
- Elenchi dei partecipanti — mostra i partecipanti attuali in un'applicazione esterna o in una pagina di lobby.
- Stato della registrazione — verificare se la registrazione è abilitata per la riunione.
- Debugging — esegui un'analisi dettagliata di una riunione specifica per finalità di risoluzione dei problemi.
getMeetingInfo è disponibile su tutti i piani. Puoi trovare le tue credenziali API nella dashboard di gestione del server.Suggerimenti
Interroga periodicamente getMeetingInfo per costruire un elenco live dei partecipanti. Combina i campi voiceParticipantCount e videoCount per determinare quanti utenti sono attivamente coinvolti con audio e video.
Usa il contenitore metadata per passare e recuperare dati specifici dell'applicazione come sistema di origine, URL di callback o etichette personalizzate senza interferire con gli elementi interni di BigBlueButton.
I campi attendeePW e moderatorPW sono deprecati da BigBlueButton 2.5. Sono ancora restituiti per compatibilità con le versioni precedenti, ma non dovresti farvi affidamento per la logica di autenticazione nelle nuove integrazioni.
Domande frequenti
FAILED con la messageKey "notFound". BigBlueButton rimuove i dati della riunione dalla memoria una volta che la riunione è terminata. Per accedere alle informazioni sulle riunioni passate, usa invece l'endpoint getRecordings.getMeetings elenca ancora gli utenti che hanno abbandonato la riunione di recente, finché BigBlueButton non li rimuove (per impostazione predefinita dopo 60 secondi).BigBlueButton stesso, ma un polling frequente (ad es. ogni secondo) può mettere un carico inutile sul server. Un intervallo di polling da 5 a 10 secondi è in genere sufficiente per la maggior parte dei casi d'uso.getMeetingInfo con meetingID. Se il returncode della risposta è SUCCESS, la riunione esiste ed è attiva. Se è FAILED con messageKey "notFound", la riunione non esiste o è già terminata.parentMeetingID, sequence, freeJoin e breakoutRooms compaiono nella risposta solo quando la riunione è una stanza per sottogruppi o ha stanze per sottogruppi. Per le riunioni normali, isBreakout è false e gli altri campi di breakout vengono omessi.customdata contiene coppie chiave-valore specifiche dell'utente, passate come parametri userdata-* quando l'utente si è unito alla riunione tramite la chiamata API join. Ogni chiave (senza il prefisso userdata-) diventa un elemento figlio XML. Se non sono stati forniti dati personalizzati, l'elemento è vuoto.