Select your language

BigBlueButton 4.0 API Changes: A Checklist for Custom Scripts and Integrations

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.

Diagram of the BigBlueButton 4.0 callbacks: create call, meeting ended GET, learning analytics POST and recording ready POST
The three callbacks your LMS can receive from a BigBlueButton 4.0 server.

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 meetingID or recordingmarks, 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=true means the meeting was created with record=true and 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/xml POST body on create. It is not read from the query string. It only works when allowOverrideClientSettingsOnCreateCall=true is set in /etc/bigbluebutton/bbb-web.properties (default false). 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= (and darklogo=) on create; the branding area must be on.
  • Colours: use customStyleUrl with a CSS file. Since 4.0.1, key elements carry stable bbb- class names (for example .bbb-navigation__item--active), so your CSS survives client updates better than selectors based on generated class names.
  • Copyright: the copyright create parameter was removed in 4.0 (it never reached the client). Use app.copyright in the override instead.
  • Typos: unknown keys are silently ignored, with a warning in the bbb-apps-akka log. On a test server, set clientSettingsOverrideStrictValidation=true and a bad override fails the create call with clientSettingsOverrideValidationError. Keep it off in production.
  • The docs example now uses clientTitle (not appName) and userSettingsStorage: "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

  1. Search your code for every parameter in the table above.
  2. Make your meeting-ended handler accept meetingID and recordingmarks, including duplicates, and authenticate it with a token.
  3. Re-test your analytics importer with poll votes from users whose IDs contain capitals or hyphens.
  4. 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.
  5. Move per-meeting branding to clientSettingsOverrideJsonUrl or the POST module, and test it with strict validation on.
  6. 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.

We use cookies

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies).