API version: 4.x latest 3.x
Chapter 2

Migrate from 3.x to 4.x

BigBlueButton 4.0 removes a number of deprecated parameters and layout values, changes several defaults and introduces new error keys. This guide lists everything you need to check in your API calls when your integration talks to a BigBlueButton 4.x server instead of a BigBlueButton 3.x server.

Scope: This guide covers the changes to API calls made by your application (create, join, insertDocument, …). It does not cover upgrading or migrating the conference servers themselves.

Good news first: endpoints, the checksum calculation, the XML response format and all recording endpoints are unchanged. Most integrations only need to adjust a few parameters. Unknown or removed parameters are silently ignored – so a removed parameter does not cause an error, but it also no longer has any effect.

Overview of All Changes

Endpoint Change Impact Action required
create lockSettingsDisableNote (singular) removed Breaking Use lockSettingsDisableNotes.
create Default media bridge is now livekit Behaviour change Check phone dial-in with guest lobby; set audioBridge if needed.
create sharedNotesEditor ignored – Etherpad removed Behaviour change Remove the parameter; shared notes always use BlockNote.
create meetingEndedURL receives meetingID and recordingmarks (4.0.1) Behaviour change Make sure your callback handler tolerates the additional parameters.
create Breakout rooms created in the client inherit meetingKeepEvents from the parent Behaviour change Usually none.
create Default of meetingLayout is now UNIFIED_LAYOUT Behaviour change Usually none; pass meetingLayout explicitly to use one of the special layouts.
create New error keys malformedXml and invalidPresentationUrl; the meeting is not created Behaviour change Check your error handling for pre-uploaded documents.
create layouts and captions removed from disabledFeatures No functional impact Remove the values from your list.
create copyright, logoutTimer, webVoice removed No functional impact Remove the parameters (they had no effect before).
create, insertDocument Max. 10 documents per call (4.0.1) Behaviour change Handle documentsDropped or split uploads.
create, join Layouts CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS and VIDEO_FOCUS removed Behaviour change Use UNIFIED_LAYOUT or one of the special layouts.
create, join New parameters lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation New Optional.
end Also ends breakout rooms created via the API Behaviour change Remove workarounds that ended isBreakout rooms separately.
insertDocument Rate limit and new error keys (4.0.1) Behaviour change Handle rateLimitExceeded and the new messageKey values.
join fullName limited to 255 characters Breaking Truncate names; handle fullNameTooLong.
join webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction and userdata-bbb_parent_room_moderator removed Behaviour change Replace as described below.
sendChatMessage New error keys for missing parameters Behaviour change Handle missingParamMeetingID and missingParamMessage.
/api/rest/clientSettings Endpoint removed Breaking Do not call it anymore; use clientSettingsOverride to customize client settings.

Changes to create

Removed Parameters

Parameter (3.x) Status in 4.x Replacement
lockSettingsDisableNote Removed (was a deprecated alias). Breaking lockSettingsDisableNotes
sharedNotesEditor Ignored. Etherpad was removed, every meeting uses BlockNote. None. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown and sharedNotesInitialContentMarkdownUrl now work for every meeting – no longer only with sharedNotesEditor=blockNote.
copyright Removed. The value was never passed to the client. Client setting public.app.copyright via clientSettingsOverride (requires allowOverrideClientSettingsOnCreateCall=true on the server) or clientSettingsOverrideJsonUrl.
logoutTimer Removed. The value was never passed to the client. —
webVoice Removed. Obsolete since the Flash client was dropped in BBB 2.3. voiceBridge
Before (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
After (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Layouts

The layout selection in the client was replaced by a single adaptive layout. UNIFIED_LAYOUT is the new default of meetingLayout, and the classic layouts are no longer accepted by meetingLayout (on create), enforceLayout (on join and getJoinUrl) and userdata-bbb_default_layout:

Removed layout values do not cause an error: the client ignores them and falls back to the next layout source (e.g. the meeting layout or the default layout).

Value in 3.x Status in 4.x Recommended value in 4.x
CUSTOM_LAYOUT (default in 3.x) Removed UNIFIED_LAYOUT
SMART_LAYOUT Removed UNIFIED_LAYOUT
PRESENTATION_FOCUS Removed UNIFIED_LAYOUT; for a presentation-only screen (e.g. a projector) PRESENTATION_ONLY
VIDEO_FOCUS Removed UNIFIED_LAYOUT; for a camera wall CAMERAS_ONLY
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY Unchanged —

CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY and MEDIA_ONLY are special layouts for hybrid or kiosk scenarios – they hide large parts of the user interface. Do not use them as a 1:1 replacement for the removed layouts in regular meetings.

Media Bridges

audioBridge, cameraBridge and screenShareBridge now default to livekit instead of bbb-webrtc-sfu. The value freeswitch is no longer valid for audioBridge: the client treats it as an unknown bridge and now falls back to livekit (previously bbb-webrtc-sfu). Use audioBridge=bbb-webrtc-sfu instead.

Phone dial-in callers on the LiveKit audio bridge skip the guest lobby, even with guestPolicy=ASK_MODERATOR. If your integration relies on moderators admitting phone participants, pass audioBridge=bbb-webrtc-sfu on create, which switches the audio bridge to FreeSWITCH.

Note for bbbserver.de customers: we are working on preserving the phone entry restriction of BigBlueButton when using LiveKit as well.

The userdata parameters userdata-bbb_listen_only_mode and userdata-bbb_transparent_listen_only are only evaluated with audioBridge=bbb-webrtc-sfu. With livekit, listen-only users always join through a muted microphone connection.

disabledFeatures Values

Value Change
layouts No longer valid – the layout selection was removed from the client. No functional impact
captions No longer valid – had no effect since BBB 3.0. Use liveTranscription to disable automatic transcription. No functional impact
pinChatMessage New: disables pinning chat messages. New
multiFunctionalMode New: disables the auxiliary sidebar panel. New
webcamGrid New: disables the avatar tiles for users without a camera while the presentation is minimized. New

Pre-uploaded Presentations

Since BBB 4.0.1, a create call uploads at most 10 documents (server setting maxPresentationsPerRequest; the default presentation is not counted). The document marked current="true" is always kept, the others follow in request order. Surplus documents are dropped, but the meeting is still created and the response contains messageKey=documentsDropped:

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>demo</meetingID>
  <!-- ... -->
  <messageKey>documentsDropped</messageKey>
  <message>...</message>
</response>

Note that messageKey can now be documentsDropped on SUCCESS. If your code treats any messageKey as an error or only checks for duplicateWarning, adjust it. Upload further documents afterwards with insertDocument.

In addition, create now checks the request body before the meeting is created: a body that is not well-formed XML fails with messageKey=malformedXml, a document URL with invalid syntax fails with messageKey=invalidPresentationUrl. In both cases the meeting is not created.

Meeting Ended Callback

Since BBB 4.0.1, the meetingEndedURL callback appends meetingID and recordingmarks to the query string of your URL (4.0.0 called the URL unchanged). Existing parameters keep their values but may be re-encoded. If your URL already contains a parameter with the same name, both values are sent – yours first.

Callback (3.x)
GET https://example.com/ended?token=a817dde5
Callback (4.0.1+)
GET https://example.com/ended?token=a817dde5
  &recordingmarks=true&meetingID=demo

If you still use meta_endCallbackUrl: the official documentation now recommends meetingEndedURL instead, because meta_* values may be exposed to users in the meeting and could leak secret tokens in the callback URL. Do not verify a signature over the raw query string, as it may be re-encoded.

Other Changes

  • Breakout rooms created in the client now inherit the effective meetingKeepEvents value of their parent meeting (previously they always used the server default defaultKeepEvents). Breakout rooms you create yourself via create with isBreakout=true still use their own meetingKeepEvents parameter.

New Parameters

Parameter Default Description
lockSettingsPresenterPolicy requireApproval "Request to Present" policy: moderatorOnly, requireApproval or freeForAll.
requireUserConsentBeforeUnmuting false With true, users must agree before a moderator unmutes them (only relevant with allowModsToUnmuteUsers=true).

The default requireApproval means that viewers can now request the presenter role in the client. If only moderators should assign the presenter role, pass lockSettingsPresenterPolicy=moderatorOnly.

All details: Create Meeting (4.x).

Changes to join

Parameter Change What to do
fullName Limited to 255 characters. Longer values are rejected with fullNameTooLong (previously unlimited). Truncate display names before building the join URL.
enforceLayout Only UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY and MEDIA_ONLY are accepted. Map old values as shown in the layout table above.
webVoiceConf Removed (value was never read). Remove the parameter.
userdata-bbb_change_layout Removed; its values smart, videoFocus, presentationFocus and custom no longer exist. Use userdata-bbb_default_layout.
userdata-enable-user-reaction Removed. Use disabledFeatures=userReactions on create or the client setting public.userReaction.enabled.
userdata-bbb_parent_room_moderator Removed in 4.0.1; it had no effect since 3.0.25. Assign the role in the breakout room with role.
userdata-bbb_hide_sidebar_navigation New: closes the sidebar navigation and sidebar panel on join. New Optional.
Before (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
After (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Changes to insertDocument

  • At most 10 documents per call (maxPresentationsPerRequest). Surplus documents are dropped, the response is still SUCCESS with messageKey=documentsDropped.
  • Rate limit per meeting: by default 30 calls per 60 seconds. Calls above the limit fail with rateLimitExceeded – retry with a delay.
  • Every FAILED response now carries a messageKey: notFound, malformedXml, invalidPresentationUrl, invalidFilename, presentationDisabled, noDocuments.

If your error handling compares the message text, switch to the messageKey. Details: Insert Presentation (4.x).

Changes to end

Ending a meeting now also ends all of its breakout rooms, including rooms created via create with isBreakout=true. Previously, only breakout rooms created from the client ended together with their parent. If your application ended such rooms with separate end calls, these calls are no longer necessary – make sure your code tolerates a breakout room that has already ended.

Changes to sendChatMessage

The messageKey for missing parameters changed: a missing message now returns missingParamMessage (previously nullError), a missing meetingID returns missingParamMeetingID (previously meetingNotFound). Length violations still return sizeError, invalid characters in meetingID still return validationError.

Removed Endpoints and HTTP-Level Changes

  • /api/rest/clientSettings was removed. Client settings are now delivered via GraphQL inside the client; customize them per meeting with clientSettingsOverride or clientSettingsOverrideJsonUrl.
  • The Etherpad-related parts of the GraphQL API were removed. Plugins or integrations that query them receive a validation error.
  • Unknown URLs below /bigbluebutton/ return 404 with a JSON body instead of an XML document.
  • Requests with more than 10,000 parameters are answered with HTTP 500.
  • CORS preflight requests without CORS configuration return 200 without Access-Control-* headers (previously 403); Vary: Origin is no longer sent.
  • All responses include the security headers X-Frame-Options, X-Content-Type-Options, Referrer-Policy and X-XSS-Protection. If you embed API responses in frames, check X-Frame-Options.

The changes to 404 responses, the parameter limit and CORS preflight requests already apply since BBB 3.0.40 (bbb-web on Grails 8); they only affect you if your servers run an older 3.0 release. The security headers are new in 4.0 – on BBB 3.0.40 they are switched off.

Unchanged

The following parts of the API are identical in 3.x and 4.x – no changes are needed:

  • Checksum calculation and supported hash algorithms (SHA-1, SHA-256, SHA-384, SHA-512)
  • isMeetingRunning, getMeetings, getMeetingInfo (parameters and response format)
  • getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack
  • Webhooks, except for the pad-content event, which no longer exists because Etherpad was removed
  • Role assignment via role on join (introduced in BBB 2.4)

Server Settings That Affect API Behaviour

These settings are configured by the server operator in bbb-web.properties, not via API parameters. If you run your own servers or your provider changes them, the behaviour of your API calls may change:

Setting Change in 4.x
allowDuplicateExtUserid Removed. Multiple joins with the same userID are now controlled by maxUserConcurrentAccesses.
defaultMeetingLayout Default UNIFIED_LAYOUT (previously CUSTOM_LAYOUT).
audioBridge, cameraBridge, screenShareBridge Default livekit.
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec New limits (defaults 10, 30, 60).
accessControlAllowOrigin Removed; CORS is configured via grails.cors.*.

Migration Checklist

Search your code for removed values: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction and clientSettings.

Clean up disabledFeatures: remove layouts and captions.

Limit display names to 255 characters and handle fullNameTooLong.

Check presentation uploads: no more than 10 documents per create/insertDocument call, handle documentsDropped and rateLimitExceeded.

Review your callback handler for meetingEndedURL: it must accept the additional parameters meetingID and recordingmarks.

Decide on new defaults: presenter requests (lockSettingsPresenterPolicy) and the guest lobby for phone participants (audioBridge).

Test against a 4.x server – in particular breakout rooms, presentation uploads and your error handling based on messageKey.

Your integration has to support both versions for a while? All changes above are backward compatible in one direction: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout and display names of at most 255 characters also work on BBB 3.0.19+ servers. Use them everywhere and your API calls run on both versions.

Looking for the previous documentation? The complete 3.x reference remains available, e.g. Create Meeting (3.x).

Frequently Asked Questions

You can – and should – do it beforehand. The recommended replacements (UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) are already supported by BBB 3.0.19. Prepare your code so that the server upgrade does not require a simultaneous release of your application.

No. BigBlueButton ignores unknown parameters, so a removed parameter silently has no effect. This is why removed parameters are easy to overlook – check your code against the lists in this guide.

No. The checksum is still calculated as sha(apiCallName + queryString + sharedSecret) with the same supported hash algorithms.

No. This guide only covers changes to the API calls made by your application. Upgrading the conference servers themselves is a separate topic and is handled by your server operator.