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.
The list of available userdata parameters is only partially covered by the official BigBlueButton documentation. Many parameters are derived from source-code analysis of settings.yml and may change between versions without notice. undocumented
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-checksumBecause 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.
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_auto_swap_layout | Boolean | — | Automatically swap the layout when a presentation is shared. |
userdata-bbb_default_layout | String | — | Set the default layout for the user. The available values depend on the client configuration. undocumented |
userdata-bbb_hide_presentation | Boolean | — | Hide the presentation area from the user. |
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 cross-site scripting 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 | — | Define custom keyboard shortcuts for the user. |
Recording and External Control Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
userdata-bbb_outside_toggle_recording | Boolean | — | Allow an external application to toggle the meeting recording on and off. |
userdata-bbb_outside_toggle_self_voice | Boolean | — | Allow an external application to toggle the user's audio on and off. |
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. undocumented |
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=trueTenant-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.cssAccessible 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=trueImportant 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. 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.settings.yml file within the BigBlueButton client source code. New parameters are frequently added without documentation updates.