Kapitel 4 GET

join – Deltag i møde

Endepunktet join genererer en URL, der gør det muligt for en bruger at gå ind i et kørende BigBlueButton-møde. Som standard omdirigerer browseren direkte til BBB-klienten. Når redirect er sat til false, returneres i stedet et XML-svar, der indeholder join-URL'en og sessionstokenet.

Endepunkt

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

Kaldet join er det eneste API-endepunkt, der kaldes direkte i slutbrugerens browser (som en omdirigerings-URL). Alle andre API-kald foretages på serversiden.

Obligatoriske parametre

Parameter Type Beskrivelse
meetingID String Påkrævet. Identifikatoren for det møde, der skal tilsluttes.
fullName String Påkrævet. Brugerens viste navn i mødet.
role Enum Påkrævet. Brugerrollen: MODERATOR eller VIEWER (ikke følsom over for store og små bogstaver). BBB 3.0+

Forældede parametre

Parameter Type Beskrivelse
password String Forældet Forældet siden BBB 3.0. Rolletildeling via adgangskode (attendeePW/moderatorPW fra create). Erstattet af role.

Valgfrie parametre

Parameter Type Standard Beskrivelse
createTime Number (Long) — Tidsstempel fra svaret på create. Forhindrer tilslutning til et møde, der blev genskabt, efter at join-URL'en blev genereret.
userID String — Applikationsspecifikt bruger-ID. Returneres i getMeetingInfo og webhooks.
avatarURL String — URL til et avatarbillede for brugeren.
webcamBackgroundURL String — URL til et brugerdefineret baggrundsbillede til webcam.
firstName String — Fornavn (bruges til sortering, ikke til visning).
lastName String — Efternavn (bruges til sortering, ikke til visning).
redirect Boolean true Når den er sat til false, returneres i stedet et XML-svar for en browseromdirigering.
errorRedirectUrl String — Alternativ URL at omdirigere til ved fejl (i stedet for standardsiden for fejl).
logoutURL String — URL at omdirigere til efter logout. Tilsidesætter værdien fra create.
guest Boolean false Markér brugeren som gæst. Underlagt mødets guestPolicy.
bot Boolean false Markér brugeren som en automatiseret agent.
excludeFromDashboard Boolean false Udelad brugeren fra dashboardet for læringsanalyse.
enforceLayout Enum — Tving et bestemt layout for denne bruger. Mulige værdier: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Udokumenteret Den officielle dokumentation angiver fejlagtigt denne værdi som PARTICIPANTS_CHAT_ONLY (uden _AND_).
auth Boolean (betinget) ‎⚠ Udokumenteret Markér brugeren som autentificeret. Betinget logik: hvis guest ikke er angivet, er standardværdien for auth true. Hvis guest=true er angivet, er standardværdien for auth false, medmindre den sættes eksplicit.
defaultLayout String — ‎⚠ Udokumenteret Standardlayout for denne bruger. Samme værdier som meetingLayout i kaldet create.
sessionName String — ‎⚠ Udokumenteret Brugerdefineret sessionsnavn. Har kun effekt i kombination med existingUserID.
existingUserID String — ‎⚠ Udokumenteret Internt bruger-ID til gentilslutning eller genforbindelse med en eksisterende session.
replaceSessionToken String — ‎⚠ Udokumenteret Token for den session, der skal erstattes (når det bruges sammen med existingUserID).

Userdata-parametre

Når du kalder join, kan du sende brugerdefinerede data som parametre af typen userdata-=. Disse gøres tilgængelige i klienten og kan styre pluginadfærd eller klientindstillinger på brugerbasis.

Visse userdata-nøgler kan blokeres på serversiden via en blokliste (getJoinUrlUserdataBlocklist).

Eksempel på anmodning

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

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

Fejlsvar

messageKey Betydning
invalidMeetingIdentifier Mødet findes ikke.
meetingForciblyEnded Mødet blev tvangsafsluttet.
maxParticipantsReached Deltagergrænsen er nået.
guestDeniedAccess Gæsten blev nægtet adgang.
invalidPassword Adgangskoden er ugyldig.
checksumError checksum er ugyldig.
mismatchCreateTimeParam createTime matcher ikke mødet.
userNotFound Ingen aktiv bruger fundet med dette ID (ved brug af existingUserID).

Brug af createTime til validering af join-URL

Parameteren createTime fungerer som en beskyttelse mod forældede join-URL'er:

Et møde oprettes og returnerer createTime: 1715261728123.

Join-URL'en genereres med createTime=1715261728123.

Mødet afsluttes og oprettes igen med en ny createTime.

Den gamle join-URL med den tidligere createTime afvises.

Dette forhindrer brugere med forældede invitationslinks i at komme ind i et nyt møde, der genbruger det samme meetingID.

På bbbserver.de genereres join-URL'en altid på serversiden med korrekt checksum og parametre. Du behøver ikke at konstruere join-URL'er manuelt.

Sikkerhedstips

Eksponér aldrig shared secret på klientsiden for at beregne join-URL'er. Generér altid join-URL'er på serversiden, og send dem videre til klienten.

  • Den genererede join-URL indeholder checksum og bør kun bruges én gang.
  • Join-URL'er bør genereres på serversiden og sendes videre til klienten.
  • Til følsomme møder skal du bruge guest=true sammen med guestPolicy=ASK_MODERATOR.

Overgangen fra password til role er en af de mest betydningsfulde breaking changes i BBB 3.0. Sørg for at opdatere din integration derefter.

Ofte stillede spørgsmål

I BBB 3.0 og senere erstatter parameteren role (MODERATOR eller VIEWER) den adgangskodebaserede rolletildeling, der blev brugt i tidligere versioner. Parameteren password er forældet og bør ikke længere bruges i nye integrationer.

I stedet for at omdirigere browseren ind i mødet returnerer serveren et XML-svar, der indeholder join-URL'en og sessionstokenet. Dette er nyttigt for server-sideintegrationer, der har brug for at inspicere svaret eller håndtere sessionstokenet programmæssigt.

Ja. Brug parameteren existingUserID sammen med det interne bruger-ID fra den forrige session for at genoprette forbindelsen. Du kan også sende replaceSessionToken for at erstatte den gamle session. Bemærk, at disse parametre er udokumenterede og kan ændres uden varsel.

Når guest er sat til true, markeres brugeren som gæst og er underlagt den guestPolicy, der blev defineret, da mødet blev oprettet. For eksempel skal moderatoren med ASK_MODERATOR godkende gæsten, før vedkommende kan komme ind.

Userdata-parametre (userdata-=) giver dig mulighed for at sende brugerdefinerede data ind i mødeklienten på brugerbasis. De kan bruges til at konfigurere klientadfærd, sende information til plugins eller tilpasse brugeroplevelsen.

Denne fejl opstår, når værdien createTime i din join-URL ikke matcher createTime for det aktuelt kørende møde. Dette sker typisk, når et møde blev afsluttet og genskabt med samme meetingID, men join-URL'en stadig indeholder den gamle createTime.