Chapter 4 GET

join – Join Meeting

The join endpoint generates a URL that allows a user to enter a running BigBlueButton meeting. By default, the browser redirects directly into the BBB client. When redirect is set to false, an XML response containing the join URL and session token is returned instead.

Endpoint

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

The join call is the only API endpoint that is invoked directly in the end user's browser (as a redirect URL). All other API calls are made server-side.

Required Parameters

Parameter Type Description
meetingID String Required. The identifier of the meeting to join.
fullName String Required. The display name of the user in the meeting.
role Enum Required. The user role: MODERATOR or VIEWER (case-insensitive). BBB 3.0+

Deprecated Parameters

Parameter Type Description
password String Deprecated Deprecated since BBB 3.0. Role assignment via password (attendeePW/moderatorPW from create). Replaced by role.

Optional Parameters

Parameter Type Default Description
createTime Number (Long) — Timestamp from the create response. Prevents joining a meeting that was recreated after the join URL was generated.
userID String — Application-specific user ID. Returned in getMeetingInfo and webhooks.
avatarURL String — URL to an avatar image for the user.
webcamBackgroundURL String — URL to a custom webcam background image.
firstName String — First name (used for sorting, not for display).
lastName String — Last name (used for sorting, not for display).
redirect Boolean true When set to false, an XML response is returned instead of a browser redirect.
errorRedirectUrl String — Alternative URL to redirect to on errors (instead of the default error page).
logoutURL String — URL to redirect to after logout. Overrides the value from create.
guest Boolean false Mark the user as a guest. Subject to the guestPolicy of the meeting.
bot Boolean false Mark the user as an automated agent.
excludeFromDashboard Boolean false Exclude the user from the learning analytics dashboard.
enforceLayout Enum — Force a specific layout for this user. Possible values: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Undocumented The official documentation incorrectly lists this value as PARTICIPANTS_CHAT_ONLY (without _AND_).
auth Boolean (conditional) ‎⚠ Undocumented Mark the user as authenticated. Conditional logic: if guest is not specified, auth defaults to true. If guest=true is specified, auth defaults to false unless explicitly set.
defaultLayout String — ‎⚠ Undocumented Default layout for this user. Same values as meetingLayout in the create call.
sessionName String — ‎⚠ Undocumented Custom session name. Only effective in combination with existingUserID.
existingUserID String — ‎⚠ Undocumented Internal user ID for rejoining or reconnecting with an existing session.
replaceSessionToken String — ‎⚠ Undocumented Token of the session to replace (when used with existingUserID).

Userdata Parameters

When calling join, you can pass custom data as userdata-<key>=<value> parameters. These are made available in the client and can control plugin behavior or client settings on a per-user basis.

Certain userdata keys can be blocked server-side via a blocklist (getJoinUrlUserdataBlocklist).

Example Request

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

Example Response (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>

Error Responses

messageKey Meaning
invalidMeetingIdentifier The meeting does not exist.
meetingForciblyEnded The meeting was forcibly ended.
maxParticipantsReached The participant limit has been reached.
guestDeniedAccess The guest was denied access.
invalidPassword The password is invalid.
checksumError The checksum is invalid.
mismatchCreateTimeParam The createTime does not match the meeting.
userNotFound No active user found with this ID (when using existingUserID).

Using createTime for Join URL Validation

The createTime parameter serves as a safeguard against stale join URLs:

A meeting is created and returns createTime: 1715261728123.

The join URL is generated with createTime=1715261728123.

The meeting ends and is recreated with a new createTime.

The old join URL with the previous createTime is rejected.

This prevents users with outdated invitation links from entering a new meeting that reuses the same meetingID.

On bbbserver.de, the join URL is always generated server-side with the correct checksum and parameters. You do not need to construct join URLs manually.

Security Tips

Never expose the shared secret on the client side to compute join URLs. Always generate join URLs server-side and pass them to the client.

  • The generated join URL contains the checksum and should only be used once.
  • Join URLs should be generated server-side and passed to the client.
  • For sensitive meetings, use guest=true together with guestPolicy=ASK_MODERATOR.

The transition from password to role is one of the most significant breaking changes in BBB 3.0. Make sure to update your integration accordingly.

Frequently Asked Questions

In BBB 3.0 and later, the role parameter (MODERATOR or VIEWER) replaces the password-based role assignment used in earlier versions. The password parameter is deprecated and should no longer be used in new integrations.

Instead of redirecting the browser into the meeting, the server returns an XML response containing the join URL and session token. This is useful for server-side integrations that need to inspect the response or manage the session token programmatically.

Yes. Use the existingUserID parameter with the internal user ID from the previous session to reconnect. You can also pass replaceSessionToken to replace the old session. Note that these parameters are undocumented and may change without notice.

When guest is set to true, the user is marked as a guest and is subject to the guestPolicy defined when the meeting was created. For example, with ASK_MODERATOR, the moderator must approve the guest before they can enter.

Userdata parameters (userdata-<key>=<value>) allow you to pass custom data into the meeting client on a per-user basis. They can be used to configure client behavior, pass information to plugins, or customize the user experience.

This error occurs when the createTime value in your join URL does not match the createTime of the currently running meeting. This typically happens when a meeting was ended and recreated with the same meetingID, but the join URL still contains the old createTime.