API-Version: 4.x neueste 3.x
Kapitel 5 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.

Geändert in BigBlueButton 4.0: fullName ist auf 255 Zeichen begrenzt, enforceLayout akzeptiert nur noch die verbleibenden Layouts, und die Parameter webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction und userdata-bbb_parent_room_moderator wurden entfernt. Einzelheiten finden Sie im Migrationsleitfaden.

Endpunkt

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

Der join-Aufruf ist der einzige durch eine Prüfsumme geschützte API-Endpunkt, der direkt im Browser des Endbenutzers aufgerufen wird (als Weiterleitungs-URL). Alle anderen durch eine Prüfsumme geschützten 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.
Seit BBB 4.0 maximal 255 Zeichen; längere Namen werden mit fullNameTooLong abgelehnt.
role Enum Erforderlich. Die Benutzerrolle: MODERATOR oder VIEWER (Groß-/Kleinschreibung wird nicht berücksichtigt). BBB 2.4+

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, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
Die Layouts CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS und VIDEO_FOCUS werden seit BBB 4.0 nicht mehr akzeptiert.
auth Boolean (bedingt) ‎⚠ Undokumentiert Markiert den Benutzer als authentifiziert. Bedingte Logik: Wenn guest nicht angegeben ist, hat auth standardmäßig den Wert true. Wenn guest angegeben ist (mit einem beliebigen Wert, einschließlich false), hat auth standardmäßig den Wert false, sofern es nicht explizit gesetzt wird.
defaultLayout String — ‎⚠ Undokumentiert In BBB 3.0 aus der offiziellen API entfernt. Der Server akzeptiert den Wert weiterhin, wertet ihn jedoch nie aus, sodass er keine Wirkung hat. Verwenden Sie userdata-bbb_default_layout, um das Layout festzulegen, mit dem der Client startet.
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.

Die serverseitige Sperrliste getJoinUrlUserdataBlocklist gilt nur für Beitritts-URLs, die über getJoinUrl generiert werden. Der join-Aufruf selbst akzeptiert alle userdata-Schlüssel.

Der Teil nach userdata- darf keinen weiteren Bindestrich enthalten, andernfalls wird der Parameter verworfen. Das Präfix userdata-bbb_ ist für BigBlueButton reserviert – verwenden Sie für Integrationsdaten ein eigenes Präfix (z. B. userdata-myapp_cohort). Eine vollständige Liste finden Sie im Kapitel Client-Einstellungen.

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>
  <guestStatus>ALLOW</guestStatus>
  <url>https://api-guide.bbbserver.com/html5client/?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.
fullNameTooLong fullName ist länger als 255 Zeichen. BBB 4.0+
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 Beitritts-URL für Teilnehmer, die über Räume oder Einladungslinks in der Weboberfläche von bbbserver.de beitreten, automatisch generiert. Wenn Sie Integration API verwenden, erstellen Sie den join-Aufruf wie oben beschrieben selbst.

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.