Capitolo 4 GET

join – Partecipa alla riunione

L'endpoint join genera un URL che consente a un utente di entrare in una riunione BigBlueButton in corso. Per impostazione predefinita, il browser reindirizza direttamente al client BBB. Quando redirect è impostato su false, viene invece restituita una risposta XML contenente l'URL di accesso e il token di sessione.

Endpoint

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum

La chiamata join è l'unico endpoint API che viene invocato direttamente nel browser dell'utente finale (come URL di reindirizzamento). Tutte le altre chiamate API vengono effettuate lato server.

Parametri obbligatori

Parametro Tipo Descrizione
meetingID String Obbligatorio. L'identificatore della riunione a cui partecipare.
fullName String Obbligatorio. Il nome visualizzato dell'utente nella riunione.
role Enum Obbligatorio. Il ruolo dell'utente: MODERATOR oppure VIEWER (maiuscole/minuscole non rilevanti). BBB 3.0+

Parametri deprecati

Parametro Tipo Descrizione
password String Deprecato Deprecato da BBB 3.0. Assegnazione del ruolo tramite password (attendeePW/moderatorPW da create). Sostituito da role.

Parametri opzionali

Parametro Tipo Predefinito Descrizione
createTime Number (Long) — Timestamp dalla risposta di create. Impedisce l'accesso a una riunione che è stata ricreata dopo la generazione dell'URL di join.
userID String — ID utente specifico dell'applicazione. Restituito in getMeetingInfo e webhooks.
avatarURL String — URL di un'immagine avatar per l'utente.
webcamBackgroundURL String — URL di un'immagine personalizzata per lo sfondo della webcam.
firstName String — Nome (usato per l'ordinamento, non per la visualizzazione).
lastName String — Cognome (usato per l'ordinamento, non per la visualizzazione).
redirect Boolean true Quando impostato su false, viene restituita una risposta XML invece di un reindirizzamento del browser.
errorRedirectUrl String — URL alternativo a cui reindirizzare in caso di errori (invece della pagina di errore predefinita).
logoutURL String — URL a cui reindirizzare dopo il logout. Sovrascrive il valore di create.
guest Boolean false Contrassegna l'utente come ospite. Soggetto alla guestPolicy della riunione.
bot Boolean false Contrassegna l'utente come agente automatico.
excludeFromDashboard Boolean false Escludi l'utente dalla dashboard di learning analytics.
enforceLayout Enum — Forza un layout specifico per questo utente. Valori possibili: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Non documentato La documentazione ufficiale elenca erroneamente questo valore come PARTICIPANTS_CHAT_ONLY (senza _AND_).
auth Boolean (condizionale) ‎⚠ Non documentato Contrassegna l'utente come autenticato. Logica condizionale: se guest non è specificato, auth assume come valore predefinito true. Se è specificato guest=true, auth assume come valore predefinito false salvo impostazione esplicita.
defaultLayout String — ‎⚠ Non documentato Layout predefinito per questo utente. Stessi valori di meetingLayout nella chiamata create.
sessionName String — ‎⚠ Non documentato Nome di sessione personalizzato. Ha effetto solo in combinazione con existingUserID.
existingUserID String — ‎⚠ Non documentato ID utente interno per rientrare o riconnettersi con una sessione esistente.
replaceSessionToken String — ‎⚠ Non documentato Token della sessione da sostituire (se usato con existingUserID).

Parametri Userdata

Quando chiami join, puoi passare dati personalizzati come parametri userdata-=. Questi vengono resi disponibili nel client e possono controllare il comportamento dei plugin o le impostazioni client per singolo utente.

Alcune chiavi userdata possono essere bloccate lato server tramite una blocklist (getJoinUrlUserdataBlocklist).

Esempio di richiesta

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum

Esempio di risposta (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
    <meeting_id>replace-with-internal-meeting-id</meeting_id>
    <user_id>replace-with-user-id</user_id>
        <auth_token>replace-with-auth-token</auth_token>
        <session_token>replace-with-session-token</session_token>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?sessionToken=replace-with-session-token</url>
</response>

Risposte di errore

messageKey Significato
invalidMeetingIdentifier La riunione non esiste.
meetingForciblyEnded La riunione è stata terminata forzatamente.
maxParticipantsReached È stato raggiunto il limite di partecipanti.
guestDeniedAccess All'ospite è stato negato l'accesso.
invalidPassword La password non è valida.
checksumError Il checksum non è valido.
mismatchCreateTimeParam Il parametro createTime non corrisponde alla riunione.
userNotFound Nessun utente attivo trovato con questo ID (quando si usa existingUserID).

Uso di createTime per la convalida dell'URL di accesso

Il parametro createTime funge da protezione contro URL di accesso obsoleti:

Viene creata una riunione e restituisce createTime: 1715261728123.

L'URL di accesso viene generato con createTime=1715261728123.

La riunione termina e viene ricreata con un nuovo createTime.

Il vecchio URL di accesso con il precedente createTime viene rifiutato.

Questo impedisce agli utenti con link di invito obsoleti di entrare in una nuova riunione che riutilizza lo stesso meetingID.

Su bbbserver.de, l'URL di accesso viene sempre generato lato server con il corretto checksum e i parametri corretti. Non è necessario costruire manualmente gli URL di accesso.

Suggerimenti di sicurezza

Non esporre mai il shared secret sul lato client per calcolare gli URL di accesso. Genera sempre gli URL di accesso lato server e passali al client.

  • L'URL di accesso generato contiene il checksum e dovrebbe essere usato una sola volta.
  • Gli URL di accesso dovrebbero essere generati lato server e passati al client.
  • Per riunioni sensibili, usa guest=true insieme a guestPolicy=ASK_MODERATOR.

La transizione da password a role è uno dei cambiamenti incompatibili più significativi in BBB 3.0. Assicurati di aggiornare di conseguenza la tua integrazione.

Domande frequenti

In BBB 3.0 e versioni successive, il parametro role (MODERATOR o VIEWER) sostituisce l'assegnazione del ruolo basata su password usata nelle versioni precedenti. Il parametro password è deprecato e non dovrebbe più essere usato nelle nuove integrazioni.

Invece di reindirizzare il browser alla riunione, il server restituisce una risposta XML contenente l'URL di accesso e il token di sessione. Questo è utile per le integrazioni lato server che devono ispezionare la risposta o gestire il token di sessione programmaticamente.

Sì. Usa il parametro existingUserID con l'ID utente interno della sessione precedente per riconnetterti. Puoi anche passare replaceSessionToken per sostituire la vecchia sessione. Nota che questi parametri non sono documentati e possono cambiare senza preavviso.

Quando guest è impostato su true, l'utente viene contrassegnato come ospite ed è soggetto alla guestPolicy definita quando è stata creata la riunione. Ad esempio, con ASK_MODERATOR, il moderatore deve approvare l'ospite prima che possa entrare.

I parametri Userdata (userdata-=) ti consentono di passare dati personalizzati al client della riunione per singolo utente. Possono essere usati per configurare il comportamento del client, passare informazioni ai plugin o personalizzare l'esperienza utente.

Questo errore si verifica quando il valore createTime nel tuo URL di accesso non corrisponde al createTime della riunione attualmente in esecuzione. In genere ciò accade quando una riunione è stata terminata e ricreata con lo stesso meetingID, ma l'URL di accesso contiene ancora il vecchio createTime.