API version: 4.x latest 3.x

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.

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 is intended to set a custom copyright text in the BBB client. Note that the value is stored by the server but not passed on to the client, so it has no visible effect; use clientSettingsOverride with public.app.copyright instead. The parameter was removed in BBB 4.0.

The logo parameter is only displayed if the client setting public.app.branding.displayBrandingArea is enabled (default: true; can be overridden per user with userdata-bbb_display_branding_area).

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-2024-38518 / 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
POST removed for /join Only GET requests are accepted for join calls.
Content-Type required Must be specified for every request that has a body (typically POST requests). Requests with a body but a missing or unsupported Content-Type are rejected.
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.3, removed in BBB 2.4. clientSettingsOverride
setConfigXML Deprecated since BBB 2.3, removed in BBB 2.4. 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 bbb-webrtc-sfu

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.

Nothing changed in BigBlueButton 3.0: the password parameter of the join call is still accepted, but it is deprecated. Since BigBlueButton 2.4 you can pass role=MODERATOR or role=VIEWER via the role parameter instead of the attendee or moderator password; if role is set, it takes precedence over 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.3 and have been removed in BBB 2.4. They have been replaced by the clientSettingsOverride parameter in the create call, which provides a more flexible way to customize client behavior per meeting.