Hoofdstuk 4 GET

join – Deelnemen aan vergadering

Het endpoint join genereert een URL waarmee een gebruiker een actieve BigBlueButton-vergadering kan betreden. Standaard leidt de browser direct door naar de BBB-client. Wanneer redirect op false staat, wordt in plaats daarvan een XML-antwoord met de join-URL en sessietoken teruggegeven.

Endpoint

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

De aanroep join is het enige API-endpoint dat direct in de browser van de eindgebruiker wordt aangeroepen (als een redirect-URL). Alle andere API-aanroepen worden server-side gedaan.

Vereiste parameters

Parameter Type Beschrijving
meetingID String Vereist. De identifier van de vergadering waaraan moet worden deelgenomen.
fullName String Vereist. De weergavenaam van de gebruiker in de vergadering.
role Enum Vereist. De gebruikersrol: MODERATOR of VIEWER (hoofdletterongevoelig). BBB 3.0+

Verouderde parameters

Parameter Type Beschrijving
password String Verouderd Verouderd sinds BBB 3.0. Roltoewijzing via wachtwoord (attendeePW/moderatorPW uit create). Vervangen door role.

Optionele parameters

Parameter Type Standaard Beschrijving
createTime Number (Long) — Tijdstempel uit de create-respons. Voorkomt deelname aan een vergadering die opnieuw is aangemaakt nadat de join-URL was gegenereerd.
userID String — Applicatiespecifieke gebruikers-ID. Geretourneerd in getMeetingInfo en webhooks.
avatarURL String — URL naar een avatarafbeelding voor de gebruiker.
webcamBackgroundURL String — URL naar een aangepaste webcamachtergrondafbeelding.
firstName String — Voornaam (gebruikt voor sortering, niet voor weergave).
lastName String — Achternaam (gebruikt voor sortering, niet voor weergave).
redirect Boolean true Wanneer ingesteld op false, wordt in plaats van een browserredirect een XML-antwoord geretourneerd.
errorRedirectUrl String — Alternatieve URL om naartoe te redirecten bij fouten (in plaats van de standaard foutpagina).
logoutURL String — URL om na logout naartoe te redirecten. Overschrijft de waarde van create.
guest Boolean false Markeer de gebruiker als gast. Onderhevig aan het guestPolicy van de vergadering.
bot Boolean false Markeer de gebruiker als een geautomatiseerde agent.
excludeFromDashboard Boolean false Sluit de gebruiker uit van het dashboard voor leeranalyses.
enforceLayout Enum — Forceer een specifieke lay-out voor deze gebruiker. Mogelijke waarden: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Ongedocumenteerd De officiële documentatie vermeldt deze waarde onjuist als PARTICIPANTS_CHAT_ONLY (zonder _AND_).
auth Boolean (voorwaardelijk) ‎⚠ Ongedocumenteerd Markeer de gebruiker als geauthenticeerd. Voorwaardelijke logica: als guest niet is opgegeven, is auth standaard true. Als guest=true is opgegeven, is auth standaard false, tenzij expliciet ingesteld.
defaultLayout String — ‎⚠ Ongedocumenteerd Standaardlay-out voor deze gebruiker. Dezelfde waarden als meetingLayout in de create-aanroep.
sessionName String — ‎⚠ Ongedocumenteerd Aangepaste sessienaam. Alleen effectief in combinatie met existingUserID.
existingUserID String — ‎⚠ Ongedocumenteerd Interne gebruikers-ID voor opnieuw deelnemen of opnieuw verbinden met een bestaande sessie.
replaceSessionToken String — ‎⚠ Ongedocumenteerd Token van de sessie die moet worden vervangen (wanneer gebruikt met existingUserID).

Userdata Parameters

Bij het aanroepen van join kun je aangepaste gegevens doorgeven als parameters van het type userdata-=. Deze worden beschikbaar gemaakt in de client en kunnen plugin-gedrag of clientinstellingen per gebruiker aansturen.

Bepaalde userdata-sleutels kunnen aan de serverzijde worden geblokkeerd via een blocklist (getJoinUrlUserdataBlocklist).

Voorbeeldverzoek

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

Voorbeeldantwoord (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>

Foutresponses

messageKey Betekenis
invalidMeetingIdentifier De vergadering bestaat niet.
meetingForciblyEnded De vergadering is geforceerd beëindigd.
maxParticipantsReached De deelnemerslimiet is bereikt.
guestDeniedAccess De gast kreeg geen toegang.
invalidPassword Het wachtwoord is ongeldig.
checksumError De checksum is ongeldig.
mismatchCreateTimeParam De createTime komt niet overeen met de vergadering.
userNotFound Geen actieve gebruiker gevonden met deze ID (bij gebruik van existingUserID).

createTime gebruiken voor validatie van join-URL's

De parameter createTime dient als beveiliging tegen verouderde join-URL's:

Er wordt een vergadering aangemaakt en createTime: 1715261728123 wordt geretourneerd.

De join-URL wordt gegenereerd met createTime=1715261728123.

De vergadering eindigt en wordt opnieuw aangemaakt met een nieuwe createTime.

De oude join-URL met de vorige createTime wordt geweigerd.

Dit voorkomt dat gebruikers met verouderde uitnodigingslinks een nieuwe vergadering kunnen betreden die dezelfde meetingID hergebruikt.

Op bbbserver.de wordt de join-URL altijd server-side gegenereerd met de juiste checksum en parameters. Je hoeft join-URL's niet handmatig op te bouwen.

Beveiligingstips

Stel de shared secret nooit bloot aan de clientzijde om join-URL's te berekenen. Genereer join-URL's altijd server-side en geef ze door aan de client.

  • De gegenereerde join-URL bevat de checksum en mag slechts één keer worden gebruikt.
  • Join-URL's moeten server-side worden gegenereerd en aan de client worden doorgegeven.
  • Gebruik voor gevoelige vergaderingen guest=true samen met guestPolicy=ASK_MODERATOR.

De overgang van password naar role is een van de belangrijkste breaking changes in BBB 3.0. Zorg ervoor dat je je integratie dienovereenkomstig bijwerkt.

Veelgestelde vragen

In BBB 3.0 en later vervangt de parameter role (MODERATOR of VIEWER) de wachtwoordgebaseerde roltoewijzing die in eerdere versies werd gebruikt. De parameter password is verouderd en mag niet langer worden gebruikt in nieuwe integraties.

In plaats van de browser naar de vergadering door te sturen, retourneert de server een XML-antwoord met de join-URL en sessietoken. Dit is nuttig voor server-side integraties die het antwoord moeten inspecteren of het sessietoken programmatisch moeten beheren.

Ja. Gebruik de parameter existingUserID met de interne gebruikers-ID uit de vorige sessie om opnieuw verbinding te maken. Je kunt ook replaceSessionToken meegeven om de oude sessie te vervangen. Let op: deze parameters zijn niet gedocumenteerd en kunnen zonder voorafgaande kennisgeving veranderen.

Wanneer guest op true is ingesteld, wordt de gebruiker gemarkeerd als gast en valt deze onder het guestPolicy dat bij het aanmaken van de vergadering is gedefinieerd. Bijvoorbeeld: bij ASK_MODERATOR moet de moderator de gast goedkeuren voordat deze kan deelnemen.

Userdata-parameters (userdata-=) maken het mogelijk om per gebruiker aangepaste gegevens door te geven aan de vergaderclient. Ze kunnen worden gebruikt om clientgedrag te configureren, informatie aan plugins door te geven of de gebruikerservaring aan te passen.

Deze fout treedt op wanneer de waarde createTime in je join-URL niet overeenkomt met de createTime van de momenteel actieve vergadering. Dit gebeurt meestal wanneer een vergadering is beëindigd en opnieuw is aangemaakt met dezelfde meetingID, terwijl de join-URL nog steeds de oude createTime bevat.