API-version: 4.x seneste 3.x

Du ser API-dokumentationen til BigBlueButton 3.x. Den aktuelle version er BigBlueButton 4.x. Planlægger du en opgradering? Migreringsvejledningen viser alle de ændringer, dine API-kald kræver.

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-endpoint beskyttet med en kontrolsum, der kaldes direkte i slutbrugerens browser (som en omdirigerings-URL). Alle andre API-kald beskyttet med en kontrolsum 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 2.4+

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.
webVoiceConf String Forældet Removed in 4.0 Brugerdefineret lokalnummer til den gamle Flash-klient. Værdien evalueres ikke og har ingen effekt.

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.
auth Boolean (betinget) ‎⚠ Udokumenteret Markér brugeren som autentificeret. Betinget logik: Hvis guest ikke er angivet, er standardværdien for auth true. Hvis guest er angivet (med en hvilken som helst værdi, herunder false), er standardværdien for auth false, medmindre den angives eksplicit.
defaultLayout String — ‎⚠ Udokumenteret Fjernet fra det officielle API i BBB 3.0. Serveren accepterer stadig værdien, men evaluerer den aldrig, så den har ingen effekt. Brug userdata-bbb_default_layout til at indstille det layout, klienten starter med.
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.

Blokeringslisten getJoinUrlUserdataBlocklist på serversiden gælder kun for deltagelses-URL'er, der genereres via getJoinUrl. Selve kaldet join accepterer alle userdata-nøgler.

Delen efter userdata- må ikke indeholde endnu en bindestreg, ellers udelades parameteren. Præfikset userdata-bbb_ er reserveret til BigBlueButton – brug dit eget præfiks til integrationsdata (f.eks. userdata-myapp_cohort). En komplet liste findes i kapitlet Klientindstillinger.

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>
  <guestStatus>ALLOW</guestStatus>
  <url>https://api-guide.bbbserver.com/html5client/?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 får deltagere, der tilslutter sig via rum eller invitationslinks i webgrænsefladen til bbbserver.de, automatisk genereret deres deltagelses-URL. Hvis du bruger Integration API, skal du selv opbygge kaldet join som beskrevet ovenfor.

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.