Chapter 21

Tips, Best Practices & Hidden Features

This chapter collects lesser-known API features, security recommendations, and proven best practices for integrating with the BigBlueButton API. Many of these details are only partially documented in the official sources and have been verified through source code analysis and community research.

Hidden Guest Policy Value

In addition to the three well-known values for the guestPolicy parameter, there is a fourth value that is rarely documented but highly useful for mixed-audience scenarios.

Value Behavior
ALWAYS_ACCEPT All users join immediately without approval.
ALWAYS_DENY Only moderators can join the meeting.
ASK_MODERATOR Guests wait in the lobby until a moderator approves them.
ALWAYS_ACCEPT_AUTH Authenticated users join directly. Only unauthenticated guests require moderator approval.

The ALWAYS_ACCEPT_AUTH policy is ideal when registered users from an LMS should join without waiting, while external guests still need to be approved by a moderator.

Server-Side Callback with meetingEndedURL

The meetingEndedURL parameter provides a server-side callback that differs from the commonly used meta_endCallbackUrl in important ways:

  • It is not exposed to the client and not stored in recordings.
  • It is used internally by systems such as Scalelite.
  • It is well suited for server-side integrations where the callback URL must remain hidden.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Breakout Room Capture Parameters

Beyond the standard breakout room parameters, BigBlueButton supports additional options for capturing content from breakout rooms back into the main meeting.

Parameter Type Description
breakoutRoomsCaptureSlides Boolean Import slides from breakout rooms into the main meeting.
breakoutRoomsCaptureNotes Boolean Import shared notes from breakout rooms into the main meeting.
breakoutRoomsCaptureNotesFilename String Custom filename for the captured notes file.

Annotation and Branding Parameters

The lockSettingsHideViewersAnnotation parameter hides whiteboard annotations made by other viewers, so that each participant only sees their own annotations and those of the presenter. 

create?meetingID=replace-with-meeting-id&lockSettingsHideViewersAnnotation=true&checksum=replace-with-checksum

The copyright parameter sets a custom copyright text in the BBB client, which can be useful for white-labeling deployments: 

create?meetingID=replace-with-meeting-id&copyright=Example+Organization&checksum=replace-with-checksum

The logo parameter only works if displayBrandingArea=true is set in the server configuration file /etc/bigbluebutton/bbb-web.properties.

Security Best Practices

Always Include createTime in Join URLs

Always include the createTime value from the create response in your join URL. This prevents old join links from being reused when a new meeting is created with the same meeting ID. 

join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&createTime=1715261728123&checksum=replace-with-checksum

Checksum Calculation for POST Requests

A common mistake: the checksum is always calculated from the URL query string only, even for POST requests. The request body (XML, JSON) is never included in the checksum calculation. 

Checksum = SHA256("create" + "meetingID=replace-with-meeting-id&name=Demo" + "replace-with-secret")

The POST body (e.g. presentation XML) is sent separately but is not hashed.

A past security vulnerability (CVE GHSA-4m48-49h7-f3c4) allowed attackers with a valid join URL to inject additional parameters into signed join links. Always validate and sanitize all parameters server-side before generating signed API URLs.

BBB 3.0 Breaking Changes

BigBlueButton 3.0 introduces several breaking changes that affect API integrations. Review the following table carefully when upgrading:

Change Details
password → role The join call now uses role=MODERATOR or role=VIEWER instead of passwords.
POST removed for /join Only GET requests are accepted for join calls.
Content-Type required Must be specified for all POST requests.
Accepted Content-Types for /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Removed parameters breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled have been replaced by the disabledFeatures parameter.

Deprecated Endpoints

The following endpoints are deprecated and should not be used in new integrations:

Endpoint Status Replacement
getDefaultConfigXML Deprecated since BBB 2.4, removed in BBB 3.0. clientSettingsOverride
setConfigXML Deprecated since BBB 2.4, removed in BBB 3.0. clientSettingsOverride

Plugin Manifest Merge Behavior

Plugin manifests from three sources are merged (not overwritten) when a meeting is created:

  1. Server configuration
  2. pluginManifests parameter in the create call
  3. pluginManifestsFetchUrl parameter

Duplicates are automatically removed. This enables flexible plugin configuration across multiple levels.

Important Server Configuration Options

The following settings from bigbluebutton.properties are not controllable via the API but directly affect API behavior:

Property Default Description
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Supported checksum algorithms for API authentication.
maxUserConcurrentAccesses 3 Maximum concurrent sessions per user (by external ID).
allowOverrideClientSettingsOnCreateCall false Enables the clientSettingsOverride parameter in the create body.
allowRevealOfBBBVersion false Shows the BBB version in the API root response.
allowFetchAllRecordings true Allows getRecordings without a meeting ID filter.
maxFileSizeUpload 30000000 Maximum file size for presentation uploads (30 MB).
defaultHttpSessionTimeout 14400 HTTP session timeout in seconds (4 hours).
sessionsCleanupDelayInMinutes 60 Sessions remain active for this many minutes after a meeting ends.
fetchUrlSupportedProtocols https Allowed protocols for URL fetching (e.g. presentation downloads).

Media Bridge Configuration

BigBlueButton 3.0 introduces LiveKit as an alternative media bridge. The following create parameters control which bridge is used:

Parameter Possible Values Default
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Presentation Conversion Timeout

Starting with BBB 3.0, the server parameter maxPageConversionTime (default: 60 seconds) limits the conversion time per slide. Complex presentations with many pages or heavy graphics may hit this timeout, causing slides to fail conversion.

If your presentations frequently time out during conversion, consider splitting them into smaller files or simplifying complex slides before uploading.

Frequently Asked Questions

It is a fourth, lesser-known value for the guestPolicy parameter. Authenticated users join immediately, while unauthenticated guests must wait for moderator approval. This is useful when LMS users should enter directly but external visitors need to be screened.

The meetingEndedURL parameter is a server-side callback that is never exposed to clients or stored in recordings. It is designed for internal integrations where the callback URL must remain private, such as in Scalelite deployments.

No. The checksum is always calculated from the URL query string only. The POST body (such as presentation XML) is sent separately and is not part of the hash. This is a common source of errors for developers new to the API.

In BigBlueButton 3.0, the password parameter for the join call has been replaced by the role parameter. You now pass role=MODERATOR or role=VIEWER instead of the attendee or moderator password.

Including the createTime value from the create response ensures that old join links cannot be reused for a new meeting created with the same meeting ID. It is an important security mechanism that prevents unauthorized access through stale URLs.

Both endpoints were deprecated in BBB 2.4 and have been removed in BBB 3.0. They have been replaced by the clientSettingsOverride parameter in the create call, which provides a more flexible way to customize client behavior per meeting.