Chapter 7 GET POST

getJoinUrl – Generate Join URL

The getJoinUrl endpoint generates a new join URL for a user who has already joined a meeting. This allows the same user to open additional sessions — for example on a second screen or after switching devices — without re-authenticating through the standard join flow. BBB 3.0+

Endpoint

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

This endpoint uses session-token authentication instead of the standard shared-secret checksum mechanism. The user must have already joined via the join endpoint and hold a valid sessionToken.

This is the only BigBlueButton API endpoint that returns JSON instead of XML.

Required Parameters

Parameter Type Required Default Description
sessionToken String Yes — The sessionToken of the user for whom a new join URL should be generated.

Optional Parameters

Parameter Type Required Default Description
replaceSession Boolean No false When set to true, the original session is invalidated and replaced by the new one (session transfer).
sessionName String No — A descriptive name for the new session.
enforceLayout String No — Override the layout for the new session.
userdata-* ↗ undocumented String No — Custom user data for the new session. Keys must be prefixed with userdata-.

Use Cases

  • Hybrid scenarios — a moderator uses one screen for the presentation and a second screen for the participant view.
  • Device switching — a user moves from their desktop to a tablet during a meeting.
  • Multi-screen setups — a conference room with multiple displays showing different layouts.

Behaviour

The new session shares the user identity with the original session. The user appears only once in the participant list.

Without replaceSession, both sessions exist in parallel.

With replaceSession=true, the original session is invalidated and the user is seamlessly transferred to the new session.

Example Request

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Example Response (Success)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
        "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Error Responses

When a request fails, the endpoint returns a JSON object with a descriptive error message: 

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>",
        "sessionToken": "replace-with-session-token"
  }
}
Message Meaning
Invalid Session The sessionToken is invalid or has expired.
Access denied The user was not found or does not have permission.
Meeting not found The meeting does not exist or is no longer running.

Userdata Blocklist

When using userdata-* parameters with getJoinUrl, a configurable blocklist (getJoinUrlUserdataBlocklist) restricts certain userdata keys for non-moderator users:

  • If the blocklist contains the value "all", all userdata parameters are blocked for viewers.
  • Moderators bypass the blocklist, except in breakout rooms.
  • The enforceLayout parameter is always allowed, regardless of the blocklist.

The endpoint is only available when the user already holds a valid sessionToken — that is, they must have joined the meeting via the standard join endpoint first. Expired tokens are rejected.

Notes for bbbserver.de Users

The getJoinUrl endpoint is available on all bbbserver.de instances running BigBlueButton 3.0 or later. If your integration needs to support multi-screen or device-switching scenarios, this endpoint provides a clean way to generate additional join URLs without requiring a second join call with moderator credentials.

For device-switching use cases, set replaceSession=true to seamlessly transfer the session to the new device. This avoids having a stale session on the old device that could cause confusion in the participant list.

Frequently Asked Questions

No. Unlike most BigBlueButton API endpoints, getJoinUrl uses session-token authentication. You pass the sessionToken parameter instead of computing a checksum with the shared secret.

No. The user must have already joined via the standard join endpoint and hold a valid, active sessionToken. The endpoint cannot be used to create initial join URLs.

Both sessions — the original and the new one — will exist in parallel. The user appears only once in the participant list, but both browser windows or devices remain active.

This is a design choice made by the BigBlueButton developers when introducing this endpoint in version 3.0. It is the only API endpoint that returns JSON. All other endpoints continue to return XML.

The getJoinUrl endpoint was introduced in BigBlueButton 3.0. It is not available in earlier versions.

Not necessarily. A configurable blocklist can restrict certain userdata keys for non-moderator users. If the blocklist is set to "all", no userdata parameters are passed for viewers. Moderators bypass the blocklist except in breakout rooms.