Hoofdstuk 7 GET POST

getJoinUrl – Deelname-URL genereren

Het endpoint getJoinUrl genereert een nieuwe join-URL voor een gebruiker die al aan een vergadering heeft deelgenomen. Hierdoor kan dezelfde gebruiker extra sessies openen — bijvoorbeeld op een tweede scherm of na het wisselen van apparaat — zonder zich opnieuw te authenticeren via de standaardflow van join. BBB 3.0+

Endpoint

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

Dit endpoint gebruikt session-token-authenticatie in plaats van het standaardmechanisme met shared-secret checksum. De gebruiker moet al via het endpoint join hebben deelgenomen en beschikken over een geldige sessionToken.

Dit is het enige BigBlueButton-API-endpoint dat JSON retourneert in plaats van XML.

Vereiste parameters

Parameter Type Vereist Standaard Beschrijving
sessionToken String Ja — De sessionToken van de gebruiker voor wie een nieuwe join-URL moet worden gegenereerd.

Optionele parameters

Parameter Type Vereist Standaard Beschrijving
replaceSession Boolean Nee false Wanneer ingesteld op true, wordt de oorspronkelijke sessie ongeldig gemaakt en vervangen door de nieuwe (sessieoverdracht).
sessionName String Nee — Een beschrijvende naam voor de nieuwe sessie.
enforceLayout String Nee — Overschrijf de lay-out voor de nieuwe sessie.
userdata-* ↗ undocumented String Nee — Aangepaste gebruikersgegevens voor de nieuwe sessie. Sleutels moeten worden voorafgegaan door userdata-.

Toepassingen

  • Hybride scenario's — een moderator gebruikt één scherm voor de presentatie en een tweede scherm voor de deelnemersweergave.
  • Wisselen van apparaat — een gebruiker schakelt tijdens een vergadering over van desktop naar tablet.
  • Opstellingen met meerdere schermen — een conferentieruimte met meerdere displays die verschillende lay-outs tonen.

Gedrag

De nieuwe sessie deelt de gebruikersidentiteit met de oorspronkelijke sessie. De gebruiker verschijnt maar één keer in de deelnemerslijst.

Zonder replaceSession bestaan beide sessies parallel.

Met replaceSession=true wordt de oorspronkelijke sessie ongeldig gemaakt en wordt de gebruiker naadloos overgezet naar de nieuwe sessie.

Voorbeeldverzoek

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Voorbeeldantwoord (succes)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
        "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Foutresponses

Wanneer een verzoek mislukt, retourneert het endpoint een object JSON met een beschrijvende foutmelding: 

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>",
        "sessionToken": "replace-with-session-token"
  }
}
Bericht Betekenis
Invalid Session De sessionToken is ongeldig of verlopen.
Access denied De gebruiker is niet gevonden of heeft geen toestemming.
Meeting not found De vergadering bestaat niet of wordt niet meer uitgevoerd.

Userdata Blocklist

Bij gebruik van userdata-*-parameters met getJoinUrl beperkt een configureerbare blocklist (getJoinUrlUserdataBlocklist) bepaalde userdata-sleutels voor gebruikers die geen moderator zijn:

  • Als de blocklist de waarde "all" bevat, worden alle userdata-parameters geblokkeerd voor viewers.
  • Moderators omzeilen de blocklist, behalve in breakout rooms.
  • De parameter enforceLayout is altijd toegestaan, ongeacht de blokkeerlijst.

Het endpoint is alleen beschikbaar wanneer de gebruiker al beschikt over een geldige sessionToken — dat wil zeggen: de gebruiker moet eerst via het standaardendpoint join aan de vergadering hebben deelgenomen. Verlopen tokens worden afgewezen.

Opmerkingen voor bbbserver.de-gebruikers

Het endpoint getJoinUrl is beschikbaar op alle bbbserver.de-instances die BigBlueButton 3.0 of later draaien. Als je integratie scenario's met meerdere schermen of apparaatswisselingen moet ondersteunen, biedt dit endpoint een nette manier om extra join-URL's te genereren zonder een tweede aanroep van join met moderatorinloggegevens te vereisen.

Stel voor scenario's met apparaatwisseling replaceSession=true in om de sessie naadloos over te dragen naar het nieuwe apparaat. Dit voorkomt een verouderde sessie op het oude apparaat die voor verwarring in de deelnemerslijst kan zorgen.

Veelgestelde vragen

Nee. In tegenstelling tot de meeste BigBlueButton-API-endpoints gebruikt getJoinUrl session-token-authenticatie. Je geeft de parameter sessionToken door in plaats van een checksum te berekenen met het gedeelde geheim.

Nee. De gebruiker moet al via het standaardendpoint join aan de vergadering hebben deelgenomen en beschikken over een geldige, actieve sessionToken. Het endpoint kan niet worden gebruikt om initiële join-URL's te maken.

Beide sessies — de oorspronkelijke en de nieuwe — bestaan dan parallel. De gebruiker verschijnt maar één keer in de deelnemerslijst, maar beide browservensters of apparaten blijven actief.

Dit is een ontwerpkeuze van de ontwikkelaars van BigBlueButton bij de introductie van dit endpoint in versie 3.0. Het is het enige API-endpoint dat JSON retourneert. Alle andere endpoints blijven XML retourneren.

Het endpoint getJoinUrl werd geïntroduceerd in BigBlueButton 3.0. Het is niet beschikbaar in eerdere versies.

Niet noodzakelijk. Een configureerbare blocklist kan bepaalde userdata-sleutels beperken voor gebruikers die geen moderator zijn. Als de blocklist op "all" staat, worden er geen userdata-parameters doorgegeven voor viewers. Moderators omzeilen de blocklist behalve in breakout rooms.