Kapitel 4 GET

join – Meeting beitreten

Der Endpunkt join erzeugt eine URL, die es einem Benutzer ermöglicht, einem laufenden BigBlueButton-Meeting beizutreten. Standardmäßig leitet der Browser direkt in den BBB-Client weiter. Wenn redirect auf false gesetzt ist, wird stattdessen eine XML-Antwort mit der Join-URL und dem Session-Token zurückgegeben.

Endpunkt

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

Der Aufruf join ist der einzige API-Endpunkt, der direkt im Browser des Endbenutzers aufgerufen wird (als Redirect-URL). Alle anderen API-Aufrufe erfolgen serverseitig.

Erforderliche Parameter

Parameter Typ Beschreibung
meetingID String Erforderlich. Die Kennung des Meetings, dem beigetreten werden soll.
fullName String Erforderlich. Der Anzeigename des Benutzers im Meeting.
role Enum Erforderlich. Die Benutzerrolle: MODERATOR oder VIEWER (Groß-/Kleinschreibung wird nicht berücksichtigt). BBB 3.0+

Veraltete Parameter

Parameter Typ Beschreibung
password String Veraltet Veraltet seit BBB 3.0. Rollenzuweisung per Passwort (attendeePW/moderatorPW aus create). Ersetzt durch role.

Optionale Parameter

Parameter Typ Standard Beschreibung
createTime Number (Long) — Zeitstempel aus der Antwort von create. Verhindert den Beitritt zu einem Meeting, das neu erstellt wurde, nachdem die Join-URL erzeugt wurde.
userID String — Anwendungsspezifische Benutzer-ID. Wird in getMeetingInfo und webhooks zurückgegeben.
avatarURL String — URL zu einem Avatarbild für den Benutzer.
webcamBackgroundURL String — URL zu einem benutzerdefinierten Webcam-Hintergrundbild.
firstName String — Vorname (wird für die Sortierung verwendet, nicht für die Anzeige).
lastName String — Nachname (wird für die Sortierung verwendet, nicht für die Anzeige).
redirect Boolean true Wenn auf false gesetzt, wird statt einer Browser-Weiterleitung eine XML-Antwort zurückgegeben.
errorRedirectUrl String — Alternative URL zur Weiterleitung bei Fehlern (anstelle der Standard-Fehlerseite).
logoutURL String — URL zur Weiterleitung nach dem Abmelden. Überschreibt den Wert aus create.
guest Boolean false Markiert den Benutzer als Gast. Unterliegt der guestPolicy des Meetings.
bot Boolean false Markiert den Benutzer als automatisierten Agenten.
excludeFromDashboard Boolean false Schließt den Benutzer vom Learning-Analytics-Dashboard aus.
enforceLayout Enum — Erzwingt ein bestimmtes Layout für diesen Benutzer. Mögliche Werte: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Undokumentiert Die offizielle Dokumentation führt diesen Wert fälschlicherweise als PARTICIPANTS_CHAT_ONLY auf (ohne _AND_).
auth Boolean (bedingt) ‎⚠ Undokumentiert Markiert den Benutzer als authentifiziert. Bedingte Logik: Wenn guest nicht angegeben ist, ist auth standardmäßig true. Wenn guest=true angegeben ist, ist auth standardmäßig false, sofern nicht ausdrücklich gesetzt.
defaultLayout String — ‎⚠ Undokumentiert Standardlayout für diesen Benutzer. Dieselben Werte wie meetingLayout im Aufruf create.
sessionName String — ‎⚠ Undokumentiert Benutzerdefinierter Sitzungsname. Nur wirksam in Kombination mit existingUserID.
existingUserID String — ‎⚠ Undokumentiert Interne Benutzer-ID zum erneuten Beitreten oder Wiederverbinden mit einer bestehenden Sitzung.
replaceSessionToken String — ‎⚠ Undokumentiert Token der zu ersetzenden Sitzung (bei Verwendung mit existingUserID).

Userdata Parameter

Beim Aufruf von join können Sie benutzerdefinierte Daten als Parameter userdata-= übergeben. Diese werden im Client verfügbar gemacht und können das Verhalten von Plugins oder Client-Einstellungen pro Benutzer steuern.

Bestimmte userdata-Schlüssel können serverseitig über eine Blockliste (getJoinUrlUserdataBlocklist) gesperrt werden.

Beispielanfrage

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

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

Fehlerantworten

messageKey Bedeutung
invalidMeetingIdentifier Das Meeting existiert nicht.
meetingForciblyEnded Das Meeting wurde zwangsweise beendet.
maxParticipantsReached Die Teilnehmergrenze wurde erreicht.
guestDeniedAccess Dem Gast wurde der Zugang verweigert.
invalidPassword Das Passwort ist ungültig.
checksumError Das checksum ist ungültig.
mismatchCreateTimeParam Die createTime stimmt nicht mit dem Meeting überein.
userNotFound Kein aktiver Benutzer mit dieser ID gefunden (bei Verwendung von existingUserID).

Verwendung von createTime zur Validierung von Join-URLs

Der Parameter createTime dient als Schutz vor veralteten Join-URLs:

Ein Meeting wird erstellt und gibt createTime: 1715261728123 zurück.

Die Join-URL wird mit createTime=1715261728123 erzeugt.

Das Meeting endet und wird mit einer neuen createTime erneut erstellt.

Die alte Join-URL mit der vorherigen createTime wird abgelehnt.

Dies verhindert, dass Benutzer mit veralteten Einladungslinks ein neues Meeting betreten, das dieselbe meetingID wiederverwendet.

Auf bbbserver.de wird die Join-URL immer serverseitig mit der korrekten checksum und den richtigen Parametern erzeugt. Sie müssen Join-URLs nicht manuell konstruieren.

Sicherheitstipps

Legen Sie die shared secret niemals clientseitig offen, um Join-URLs zu berechnen. Erzeugen Sie Join-URLs immer serverseitig und übergeben Sie sie an den Client.

  • Die erzeugte Join-URL enthält das checksum und sollte nur einmal verwendet werden.
  • Join-URLs sollten serverseitig erzeugt und an den Client übergeben werden.
  • Für sensible Meetings verwenden Sie guest=true zusammen mit guestPolicy=ASK_MODERATOR.

Der Übergang von password zu role ist eine der bedeutendsten Breaking Changes in BBB 3.0. Stellen Sie sicher, dass Sie Ihre Integration entsprechend aktualisieren.

Häufig gestellte Fragen

In BBB 3.0 und höher ersetzt der Parameter role (MODERATOR oder VIEWER) die passwortbasierte Rollenzuweisung, die in früheren Versionen verwendet wurde. Der Parameter password ist veraltet und sollte in neuen Integrationen nicht mehr verwendet werden.

Anstatt den Browser in das Meeting weiterzuleiten, gibt der Server eine XML-Antwort zurück, die die Join-URL und das Session-Token enthält. Dies ist nützlich für serverseitige Integrationen, die die Antwort prüfen oder das Session-Token programmatisch verwalten müssen.

Ja. Verwenden Sie den Parameter existingUserID mit der internen Benutzer-ID aus der vorherigen Sitzung, um die Verbindung wiederherzustellen. Sie können auch replaceSessionToken übergeben, um die alte Sitzung zu ersetzen. Beachten Sie, dass diese Parameter undokumentiert sind und sich ohne Vorankündigung ändern können.

Wenn guest auf true gesetzt ist, wird der Benutzer als Gast markiert und unterliegt der guestPolicy, die beim Erstellen des Meetings definiert wurde. Zum Beispiel muss bei ASK_MODERATOR der Moderator den Gast bestätigen, bevor er eintreten kann.

Userdata-Parameter (userdata-=) ermöglichen es Ihnen, benutzerdefinierte Daten pro Benutzer an den Meeting-Client zu übergeben. Sie können verwendet werden, um das Client-Verhalten zu konfigurieren, Informationen an Plugins zu übergeben oder das Benutzererlebnis anzupassen.

Dieser Fehler tritt auf, wenn der Wert createTime in Ihrer Join-URL nicht mit dem createTime des aktuell laufenden Meetings übereinstimmt. Das passiert typischerweise, wenn ein Meeting beendet und mit derselben meetingID neu erstellt wurde, die Join-URL aber noch das alte createTime enthält.