You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.
userdata – Client Settings
Userdata parameters let you override client-side settings on a per-user basis by appending userdata- prefixed parameters to the join API call. This allows you to customise the BigBlueButton experience for individual participants without changing the server configuration.
In BigBlueButton 3.0, the userdata parameters are not listed in the API reference but in the administration guide (Customize, section "Passing user metadata to the client on join"). Parameters can change between versions without notice.
How Userdata Parameters Work
Userdata parameters are passed as URL query parameters on the join request. They override the default values from settings.yml for that single user session only. The parameter names always start with the userdata- prefix followed by the setting key.
GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&userdata-bbb_auto_join_audio=true&userdata-bbb_skip_check_audio=true&checksum=replace-with-checksum Because userdata parameters are part of the query string, they are included in the checksum calculation. Make sure to add them before computing the checksum, not after.
The part after userdata- must not contain another hyphen – otherwise the parameter is dropped. The prefix userdata-bbb_ is reserved for BigBlueButton; integrations that attach their own per-user data should use their own prefix, for example userdata-myapp_cohort=2026A. Such parameters are stored with the user and written to the recording events, but ignored by the client.
Audio and Media Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_auto_join_audio | Boolean | — | Automatically join the audio bridge when the user enters the meeting. |
userdata-bbb_listen_only_mode | Boolean | — | Enable or disable listen-only mode for the user. |
userdata-bbb_force_listen_only | Boolean | — | Force the user into listen-only mode. This does not apply to moderators. |
userdata-bbb_skip_check_audio | Boolean | — | Skip the audio test dialog when joining. |
userdata-bbb_skip_echotest_if_previous_device | Boolean | — | Skip the echo test if the same audio device as the previous session is detected. |
Webcam Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_auto_share_webcam | Boolean | — | Automatically start sharing the webcam when the user joins. |
userdata-bbb_mirror_own_webcam | Boolean | — | Mirror the user's own webcam preview horizontally. |
Layout and Display Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_default_layout | String | — | Layout the client starts in. enforceLayout on join takes precedence; without either, the meeting layout is used. Accepts the same values as meetingLayout on create. BBB 3.0+ |
userdata-bbb_change_layout Removed in 4.0 | String | — | Legacy layout switch. Accepts the same values as meetingLayout on create (for example SMART_LAYOUT) and takes precedence over userdata-bbb_default_layout. Use userdata-bbb_default_layout instead. |
userdata-bbb_hide_presentation_on_join | Boolean | false | Start with the presentation area minimized; the user can restore it. BBB 2.6+ |
userdata-bbb_prefer_dark_theme | Boolean | — | Activate the dark theme for the user interface. |
Customisation and Branding Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_custom_style | String | — | Inline CSS rules (URL-encoded) applied to the BigBlueButton client for this user. |
userdata-bbb_custom_style_url | URL | — | URL to an external CSS file loaded by the client for custom styling. Must be served over HTTPS. |
The userdata-bbb_custom_style parameter can be exploited for CSS injection if join URLs are constructed on the client side. Always generate join URLs on the server where you control the parameter values.
UI Element Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_hide_notifications | Boolean | — | Hide notification pop-ups in the client interface. |
userdata-bbb_hide_controls | Boolean | — | Hide the UI control elements (toolbar buttons) from the user. |
userdata-bbb_shortcuts | String | — | JSON array of the keyboard shortcuts that stay enabled (e.g. ["toggleMute","raiseHand"]); an empty array disables all shortcuts. |
userdata-enable-user-reaction Removed in 4.0 | Boolean | — | Read by the client, but bbb-web drops every userdata- parameter whose key contains a hyphen, so this parameter never reaches the client and has no effect. Use the userReactions value of disabledFeatures instead. |
Whiteboard Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_initial_selected_tool | String | — | Set the initially selected whiteboard tool when the user opens the whiteboard. The accepted values are determined by the client configuration. |
Practical Examples
Below are common combinations of userdata parameters for typical use cases.
Kiosk Mode
Ideal for conference room screens or digital signage where no user interaction is required:
userdata-bbb_auto_join_audio=true&userdata-bbb_force_listen_only=true&userdata-bbb_hide_controls=true Tenant-Specific Branding
Apply a custom CSS stylesheet per tenant or customer:
userdata-bbb_custom_style_url=https://api-guide.bbbserver.com/tenant-a/bbb-style.css Accessible Quick-Join
Streamline the join process for users who need a simplified, accessible experience:
userdata-bbb_skip_check_audio=true&userdata-bbb_auto_join_audio=true&userdata-bbb_prefer_dark_theme=true Important Notes
- Userdata parameters only affect the current session of the individual user. They do not change the server defaults.
- Not all parameters are available in every BigBlueButton version. Test against your target version before deploying.
- CSS loaded via
userdata-bbb_custom_style_urlmust be served over HTTPS.
When using the getJoinUrl endpoint, certain userdata parameters are blocked for viewers (role VIEWER) as a security measure. The blocklist is configured server-side via the getJoinUrlUserdataBlocklist property in bigbluebutton.properties. This prevents viewers from overriding security-critical client settings through pre-signed join URLs. Inside breakout rooms, the blocklist also applies to moderators. undocumented
Frequently Asked Questions
userdata-bbb_force_listen_only parameter only applies to viewers. Moderators are not forced into listen-only mode regardless of this setting.getFromUserSettings in the HTML5 client) is the authoritative reference.