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.
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 protetto da checksum che viene richiamato direttamente nel browser dell'utente finale (come URL di reindirizzamento). Tutte le altre chiamate API protette da checksum 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 2.4+ |
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. |
webVoiceConf | String | Deprecato Removed in 4.0 Interno telefonico personalizzato per il vecchio client Flash. Il valore non viene valutato e non ha alcun effetto. |
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. |
auth | Boolean | (condizionale) | ⚠ Non documentato
Contrassegna l'utente come autenticato. Logica condizionale: se guest non è specificato, auth assume il valore predefinito true. Se guest è specificato (con qualsiasi valore, incluso false), auth assume il valore predefinito false, salvo impostazione esplicita. |
defaultLayout | String | — | ⚠ Non documentato
Rimosso dall'API ufficiale in BBB 3.0. Il server accetta ancora il valore, ma non lo valuta mai, quindi non ha alcun effetto. Usa userdata-bbb_default_layout per impostare il layout iniziale del client. |
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.
L'elenco di blocco lato server getJoinUrlUserdataBlocklist si applica solo agli URL di accesso generati tramite getJoinUrl. La chiamata join stessa accetta tutte le chiavi userdata.
La parte dopo userdata- non deve contenere un altro trattino, altrimenti il parametro viene scartato. Il prefisso userdata-bbb_ è riservato a BigBlueButton: usa un tuo prefisso per i dati di integrazione (ad es. userdata-myapp_cohort). Un elenco completo è disponibile nel capitolo Impostazioni client.
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>
<guestStatus>ALLOW</guestStatus>
<url>https://api-guide.bbbserver.com/html5client/?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.
join come descritto sopra.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=trueinsieme aguestPolicy=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
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.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.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.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.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.