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 |
create?meetingID=demo&name=Demo
&lockSettingsDisableNote=true
&sharedNotesEditor=blockNote
©right=Example+Inc.
&meetingLayout=SMART_LAYOUTcreate?meetingID=demo&name=Demo
&lockSettingsDisableNotes=true
&clientSettingsOverrideJsonUrl=https%3A%2F%2F
example.com%2Fclient-settings.json
&meetingLayout=UNIFIED_LAYOUTLayouts
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.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoIf 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
meetingKeepEventsvalue of their parent meeting (previously they always used the server defaultdefaultKeepEvents). Breakout rooms you create yourself viacreatewithisBreakout=truestill use their ownmeetingKeepEventsparameter.
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. |
join?meetingID=demo&role=VIEWER
&fullName=<any length>
&enforceLayout=PRESENTATION_FOCUS
&userdata-bbb_change_layout=smartjoin?meetingID=demo&role=VIEWER
&fullName=<max. 255 characters>
&enforceLayout=UNIFIED_LAYOUT
&userdata-bbb_default_layout=UNIFIED_LAYOUTChanges to insertDocument
- At most 10 documents per call (
maxPresentationsPerRequest). Surplus documents are dropped, the response is stillSUCCESSwithmessageKey=documentsDropped. - Rate limit per meeting: by default 30 calls per 60 seconds. Calls above the limit fail with
rateLimitExceeded– retry with a delay. - Every
FAILEDresponse now carries amessageKey: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/clientSettingswas removed. Client settings are now delivered via GraphQL inside the client; customize them per meeting withclientSettingsOverrideorclientSettingsOverrideJsonUrl.- The Etherpad-related parts of the GraphQL API were removed. Plugins or integrations that query them receive a validation error.
- Unknown URLs below
/bigbluebutton/return404with 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
200withoutAccess-Control-*headers (previously403);Vary: Originis no longer sent. - All responses include the security headers
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyandX-XSS-Protection. If you embed API responses in frames, checkX-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-contentevent, which no longer exists because Etherpad was removed - Role assignment via
roleonjoin(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
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.sha(apiCallName + queryString + sharedSecret) with the same supported hash algorithms.