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.
getJoinUrl – Genera URL di accesso
L'endpoint getJoinUrl genera un nuovo URL di accesso per un utente che è già entrato in una riunione. Ciò consente allo stesso utente di aprire sessioni aggiuntive — ad esempio su un secondo schermo o dopo aver cambiato dispositivo — senza riautenticarsi tramite il normale flusso join. BBB 3.0+
Endpoint
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters> Questo endpoint usa l'session-token autenticazione invece del meccanismo standard di shared-secret checksum. L'utente deve essere già entrato tramite l'endpoint join e possedere un sessionToken valido.
A differenza degli endpoint API BigBlueButton protetti da checksum, che restituiscono XML, questo endpoint restituisce JSON.
Parametri obbligatori
| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|---|
sessionToken | String | Sì | — | Il sessionToken dell'utente per cui deve essere generato un nuovo URL di accesso. |
Parametri opzionali
| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|---|
replaceSession | Boolean | No | false | Se impostato su true, la sessione originale viene invalidata e sostituita da quella nuova (trasferimento di sessione). |
sessionName | String | No | — | Un nome descrittivo per la nuova sessione. |
enforceLayout | String | No | — | Sovrascrivi il layout per la nuova sessione. |
userdata-* | String | No | — | Dati utente personalizzati per la nuova sessione. Le chiavi devono avere il prefisso userdata-. |
Casi d’uso
- Scenari ibridi — un moderatore usa uno schermo per la presentazione e un secondo schermo per la vista partecipante.
- Cambio di dispositivo — un utente passa dal desktop a un tablet durante una riunione.
- Configurazioni multi-schermo — una sala conferenze con più display che mostrano layout differenti.
Comportamento
La nuova sessione condivide l'identità utente con la sessione originale. L'utente appare una sola volta nell'elenco dei partecipanti.
Senza replaceSession, entrambe le sessioni esistono in parallelo.
Con replaceSession=true, la sessione originale viene invalidata e l'utente viene trasferito senza interruzioni alla nuova sessione.
Esempio di richiesta
GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS Esempio di risposta (successo)
{
"response": {
"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
}
} Risposte di errore
Quando una richiesta fallisce, l'endpoint restituisce un oggetto JSON con un messaggio di errore descrittivo:
{
"response": {
"returncode": "FAILED",
"message": "<error message>"
}
} | Messaggio | Significato |
|---|---|
You must provide a session token | Manca il parametro sessionToken. |
Invalid session token | Il sessionToken non è valido o è scaduto. |
Invalid Session | La richiesta non include il cookie di sessione HTTP creato da join e la riunione non consente richieste senza una sessione (allowRequestsWithoutSession, valore predefinito false). |
Access denied | L'utente non è stato trovato oppure non dispone dei permessi necessari. |
Meeting not found | La riunione non esiste o non è più in corso. |
In BigBlueButton 3.0, solo Meeting not found viene restituito come errore JSON. Per gli altri errori elencati sopra, l'endpoint non invia alcuna risposta JSON.
Blocklist Userdata
Quando si usano parametri userdata-* con getJoinUrl, una blocklist configurabile (getJoinUrlUserdataBlocklist) limita determinate chiavi userdata per gli utenti non moderatori:
- Se la blocklist contiene il valore
"all", tutti i parametri userdata sono bloccati per i visualizzatori. - I moderatori ignorano la blocklist, tranne in breakout rooms.
- Il parametro
enforceLayoutè sempre consentito, indipendentemente dalla blocklist.
L'endpoint è disponibile solo quando l'utente possiede già un sessionToken valido — cioè deve prima essere entrato nella riunione tramite il normale endpoint join. I token scaduti vengono rifiutati.
Per i casi d'uso di cambio dispositivo, imposta replaceSession=true per trasferire senza interruzioni la sessione al nuovo dispositivo. Questo evita di avere una sessione obsoleta sul vecchio dispositivo che potrebbe causare confusione nell'elenco dei partecipanti.