Most of the attention on BigBlueButton 4.0 has gone to the new classroom interface. If you run your own scripts against the BigBlueButton API, such as an LMS connector, a webhook receiver, an analytics importer or a recording processor, the changes under the hood matter more. Some parameters are gone, some callbacks now send extra values, and a few defaults changed.
This post is a reference, not a tutorial. It lists what changed between 3.0 and 4.0 (up to 4.0.2, released 6 November 2026) based on the official API reference, the 4.0 notes for administrators and the BigBlueButton source code. Use it to check whether your parameters, callbacks and parsers still work before you move to 4.0.
1. Meeting ended callback: now with meetingID and recordingmarks
You register the callback with the meetingEndedURL parameter on create. When the meeting ends, BigBlueButton makes an HTTP GET request to that URL.
What changed: since 4.0.1, BigBlueButton appends two query parameters to your meetingEndedURL: meetingID (the ID you passed on create) and recordingmarks=true|false. In 3.0 and 4.0.0 the URL was called unchanged. The older meta_endCallbackUrl metadata parameter already received both values, and it still works in 4.0.2, but the docs now say applications should no longer use it, because meta_* values may be visible to users in the meeting.
# create
&meetingEndedURL=https%3A%2F%2Flms.example.com%2Fended%3Ftoken%3Da817dde5
# BigBlueButton 4.0.1+ calls
GET https://lms.example.com/ended?token=a817dde5&recordingmarks=true&meetingID=test01
- If your URL already contains
meetingIDorrecordingmarks, the callback carries both values, yours first. A strict parser that rejects duplicate parameters will break. - BigBlueButton may re-encode your existing parameters, so don't verify a signature over the raw query string. Use an unguessable token or a signed JWT in the URL instead.
recordingmarks=truemeans the meeting was created withrecord=trueand recording was started during the session. It is a hint, not a promise that a recording will be published.- The API page doesn't document timeouts or retries. The BigBlueButton 4.0.2 source (its API conformance tests) shows that end callbacks go to https URLs only by default, redirects are not followed, a callback has 10 seconds to answer, and a non-2xx answer is retried up to five times in total (after 30 seconds, then 1, 2 and 5 minutes). Breakout rooms do not send their own end callback.
2. Learning analytics callback: same fields, one key-format change
You register it with meta_analytics-callback-url on create. After the meeting, a recording post-events script posts the full learning analytics data as JSON. Per the script's own header in the source code, it only runs when the server keeps meeting events (keepEvents/meetingKeepEvents).
We compared the script that builds the payload (post_events_analytics_callback.rb) in v3.0.40 and v4.0.2, and the bbbevents library that both use (version 2.0.3 in both). The fields are the same in both versions (the top-level, attendee and engagement fields are listed in the API docs, which did not change; the poll sub-fields come from the bbbevents source):
| Field | 3.0 | 4.0 | Note |
|---|---|---|---|
version |
"1.0" | "1.0" | Unchanged |
meeting_id, internal_meeting_id |
Yes | Yes | Unchanged |
data.metadata |
Yes | Yes | Keys converted to snake_case in both; gl_* keys and meeting_id removed in both |
data.duration, start, finish, files |
Yes | Yes | Unchanged |
data.attendees[]: ext_user_id, name, moderator, joins, leaves, duration, recent_talking_time, engagement, sessions |
Yes | Yes | Unchanged. Internal id removed in both |
engagement: chats, talks, raisehand, emojis, poll_votes, talk_time |
Yes | Yes | Unchanged |
data.polls[]: id, type, question, published, options, start, votes |
Yes | Yes | Changed: keys inside votes (see below) |
The one change: in 3.0 the script converted every key in the whole payload to snake_case. That step is gone in 4.0, where only the metadata keys are converted. The keys of polls[].votes are external user IDs, so in 3.0 an ID like MoodleUser-12 could arrive as moodle_user_12. In 4.0 it arrives exactly as your LMS sent it and matches attendees[].ext_user_id. IDs made only of lowercase letters, digits and underscores are not affected; lowercase IDs with hyphens are (in 3.0 user-12 became user_12). If you wrote code to undo the 3.0 conversion, remove it.
Two details that are not in the API page but are in the source: the request carries Authorization: Bearer <JWT>, signed with HS512 and your shared secret, containing only an exp claim 24 hours ahead. And the script makes one POST and logs the result. We found no retry logic.
3. Recording ready callback: unchanged
You register it with meta_bbb-recording-ready-url. When a recording is published, BigBlueButton posts a form with one field, signed_parameters, a JWT signed with HS256 and your shared secret. Its payload is {"meeting_id": "...", "record_id": "..."}. The docs section is the same in 3.0 and 4.0, and the script only had internal changes (logging and how it reads the server properties). It still falls back to meta_bn-recording-ready-url and meta_canvas-recording-ready-url. Answer with any 2xx when you have stored the notification; 410 tells BigBlueButton the meeting was deleted in your app.
4. clientSettingsOverride: per-meeting branding
clientSettingsOverride is not new in 4.0 (it arrived during 3.0), but the 4.0 docs make the rules clearer, and with the redesigned client it is the cleanest way to brand rooms per customer. It overrides values from the client's settings.yml for one meeting. You can pass it two ways:
- POST module: an XML module in an
application/xmlPOST body oncreate. It is not read from the query string. It only works whenallowOverrideClientSettingsOnCreateCall=trueis set in/etc/bigbluebutton/bbb-web.properties(defaultfalse). The POST body is not covered by the checksum, so only enable it where users can't see your signed create requests. clientSettingsOverrideJsonUrl: a URL to a JSON file with the same structure. It is part of the checksummed query, needs no server setting, and wins if both are present.
A branding example using keys that exist in the 4.0.2 settings.yml:
{
"public": {
"app": {
"clientTitle": "Acme Academy Live",
"copyright": "©2026 Acme Academy",
"helpLink": "https://acme.example/help",
"showHelpButton": true,
"displayBbbServerVersion": false,
"customStyleUrl": "https://acme.example/bbb/brand.css",
"branding": { "displayBrandingArea": true },
"darkTheme": { "enabled": true }
}
}
}
- Logo: not a client setting. Pass
logo=(anddarklogo=) oncreate; the branding area must be on. - Colours: use
customStyleUrlwith a CSS file. Since 4.0.1, key elements carry stablebbb-class names (for example.bbb-navigation__item--active), so your CSS survives client updates better than selectors based on generated class names. - Copyright: the
copyrightcreate parameter was removed in 4.0 (it never reached the client). Useapp.copyrightin the override instead. - Typos: unknown keys are silently ignored, with a warning in the bbb-apps-akka log. On a test server, set
clientSettingsOverrideStrictValidation=trueand a bad override fails the create call withclientSettingsOverrideValidationError. Keep it off in production. - The docs example now uses
clientTitle(notappName) anduserSettingsStorage: "local". If you copied the old example, update it.
5. Check this in your scripts
| Parameter / endpoint | What changed in 4.0 | What to do |
|---|---|---|
meetingLayout (create), enforceLayout (join) |
Default is now UNIFIED_LAYOUT. CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS removed |
Replace with UNIFIED_LAYOUT or one of CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY |
lockSettingsDisableNote |
Singular alias removed | Use lockSettingsDisableNotes |
copyright, logoutTimer, webVoice (create); webVoiceConf (join) |
Removed (they had no effect) | Delete them; use app.copyright via override |
sharedNotesEditor |
Etherpad removed; ignored, always BlockNote | Delete it; check any Etherpad export code |
audioBridge |
freeswitch no longer listed; bridges default to livekit |
Use livekit or bbb-webrtc-sfu |
disabledFeatures |
layouts and captions removed; new multiFunctionalMode, pinChatMessage, webcamGrid |
Update your feature lists |
| New create parameters | requireUserConsentBeforeUnmuting, lockSettingsPresenterPolicy (default requireApproval), notifyRecordingAppend |
Optional; set lockSettingsPresenterPolicy=moderatorOnly if viewers must not request to present |
fullName (join) |
Max 255 characters, otherwise fullNameTooLong |
Truncate long names |
userdata-bbb_change_layout, userdata-enable-user-reaction, userdata-bbb_parent_room_moderator |
Removed | Use userdata-bbb_default_layout and the userReactions feature flag |
Pre-upload on create, insertDocument (4.0.1) |
By default at most 10 documents per call (maxPresentationsPerRequest; on create the default presentation is not counted; extra ones are dropped with documentsDropped); insertDocument limited by default to 30 calls per 60 s per meeting (rateLimitExceeded); every FAILED insertDocument answer has a messageKey |
Check messageKey even on SUCCESS; batch uploads |
end |
Also ends breakout rooms created with isBreakout=true |
Don't expect API-created breakouts to outlive the parent |
meetingKeepEvents |
Breakouts inherit the parent's value | Review analytics for breakouts |
meetingExpireWhenLastUserLeftInMinutes=0 |
4.0 docs: 0 ends the meeting as soon as the last user leaves (3.0 docs said 0 disables it) | Don't use 0 to mean "never"; test on staging |
/api/rest/clientSettings |
Removed; settings served through GraphQL | Stop calling it |
| bbb-web responses | API pages send X-Frame-Options: SAMEORIGIN; unknown URLs return a JSON 404 body |
Don't embed API responses in an iframe; don't parse 404 bodies as XML |
| Plugins | Plugin SDK 1.0.0-beta.3; manifests with only 0.x requiredSdkVersion ranges are rejected |
Update manifests, for example ^1.0.0-beta.1 |
What did not change in the docs: the checksum rules (SHA-1, SHA-256, SHA-384 and SHA-512 through supportedChecksumAlgorithms), the documented response fields of getMeetings, getMeetingInfo and getRecordings, and the webhooks documentation page. Docs that didn't change are not proof that behaviour didn't, so still run your parsers against a 4.0 server.
Pre-upgrade checklist
- Search your code for every parameter in the table above.
- Make your meeting-ended handler accept
meetingIDandrecordingmarks, including duplicates, and authenticate it with a token. - Re-test your analytics importer with poll votes from users whose IDs contain capitals or hyphens.
- Check that your meeting-ended callback URL is https and answers 2xx within 10 seconds (the limits the source code shows), and use https for the other callbacks too.
- Move per-meeting branding to
clientSettingsOverrideJsonUrlor the POST module, and test it with strict validation on. - Run a full meeting on a 4.0 test server: create, join, record, end, then check all three callbacks and
getRecordings.
FAQ
Will my 3.0 integration break on 4.0?
The create, join and end calls work the same way in the docs, but some of their parameters and behaviour changed (layouts, removed parameters, the fullName limit, end now ending API-created breakouts) and the callbacks send different data. Check the table above and test before you switch.
Do I have to change my learning analytics importer?
Only if your external user IDs contain capital letters or hyphens and you rely on the keys of polls[].votes. All other fields are the same.
Is clientSettingsOverride safe to enable?
The POST module is outside the checksum, so enable it only where create requests stay server-side. clientSettingsOverrideJsonUrl is covered by the checksum and needs no server setting.
Can I still use meta_endCallbackUrl?
It still works in 4.0.2, but the docs say not to use it. Switch to meetingEndedURL.
Test your integration on BigBlueButton 4.0 with MynaParrot
MynaParrot is a BigBlueButton hosting partner for schools, universities and training companies. We can audit your scripts and test your LMS integration, callbacks and branding on a BigBlueButton 4.0 staging server before you move production. Contact our team or try it for free.
Our free BBB Toolkit helps you check API checksums and look up error codes. These tools are for BigBlueButton; MynaParrot is not affiliated with BigBlueButton.