Versione API: 4.x più recente 3.x

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.

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 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.
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 l'hanno abbandonata non sono più inclusi. Al contrario, getMeetings elenca ancora gli utenti che hanno abbandonato la riunione di recente, finché BigBlueButton non li rimuove (per impostazione predefinita dopo 60 secondi).

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, 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.