Capitolo 10 GET POST

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 riunione viene registrata.
hasBeenForciblyEnded Boolean Se la riunione è stata terminata da una chiamata API end.
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 partecipanti che stanno condividendo la propria webcam.
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 della riunione padre. Presente solo per le breakout room.
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 interno di BigBlueButton, tipicamente nel formato w_xxxxxxxx.
fullName String Il nome visualizzato del partecipante.
role Enum Il ruolo del partecipante: MODERATOR o VIEWER.
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 dati personalizzati chiave-valore come elementi figlio XML. Presente solo quando sono stati impostati dati personalizzati per il partecipante durante join.

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>
    </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>We could not find a meeting with that meeting ID</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 Tutti gli utenti, compresi quelli che hanno lasciato 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 — verifica se la registrazione è attualmente attiva per la riunione.
  • Debugging — esegui un'analisi dettagliata di una riunione specifica per finalità di risoluzione dei problemi.
Su bbbserver.de, l'endpoint 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

Riceverai una risposta 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.

No. L'elenco dei partecipanti contiene solo i partecipanti attualmente connessi alla riunione. Gli utenti che hanno lasciato non sono più inclusi. Al contrario, getMeetings può includere utenti che hanno lasciato in alcune versioni di BigBlueButton.

Non esiste un limite rigido di frequenza imposto da 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.

Sì. Chiama 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.

Campi come 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.

Il contenitore customdata contiene coppie chiave-valore specifiche dell'utente che sono state passate come parametri quando l'utente è entrato nella riunione tramite la chiamata API join. Ogni chiave diventa un elemento figlio XML. Se non sono stati forniti dati personalizzati, questo elemento può essere assente.