BigBlueButton API (3.0)

Download OpenAPI specification:

URL: https://www.bigbluemeeting.com/ License: LGPL-3.0

Server-to-server HTTP API for BigBlueButton

The BigBlueButton API enables server-to-server integration with a BigBlueButton server. All calls are HTTPS GET (or POST) requests to https://<your-host>/bigbluebutton/api/<callName> with a checksum query-string parameter computed from the call name, the entire query string, and a shared secret (securitySalt in /etc/bigbluebutton/bbb-web.properties).

The "Try it" panel is intentionally disabled — calls require a server-side checksum that Redoc cannot compute from the browser. For working examples, see:

Version history

Updated in 0.9.0:

join — configToken may reference a file in /var/bigbluebutton/configs, e.g. myconfig.xml.
create — added moderatorOnlyMessage, autoStartRecording, allowStartStopRecording.

Updated in 1.0:

getMeetings — added fields to returned XML.
getMeetingInfo — added fields, deprecated some parameters.
getRecordings — added meta and state parameters.

Updated in 1.1:

create, getMeetings, getMeetingInfo — added returned fields.
getRecordings — returns slide thumbnails + <participants>N</participants>.
updateRecordings — meta parameters can be edited.

Updated in 2.0:

create — added bannerText, bannerColor, logo, copyright, muteOnStart.
getMeetings — returns all getMeetingInfo fields.
getMeetingInfo — added <client> field (FLASH or HTML5).

Updated in 2.2:

create — added endWhenNoModerator.
getRecordingTextTracks — list captions/subtitles for a recording.
putRecordingTextTrack — upload a caption or subtitle file.

Updated in 2.3:

create — renamed keepEvents → meetingKeepEvents, removed joinViaHtml5, added endWhenNoModeratorDelayInMinutes.
getDefaultConfigXML, setConfigXML — obsolete.

Updated in 2.4:

getDefaultConfigXML, setConfigXML — removed.
create — added meetingLayout, learningDashboardEnabled, learningDashboardCleanupDelayInMinutes, allowModsToEjectCameras, virtualBackgroundsDisabled, allowRequestsWithoutSession, userCameraCap. Length constraints: name, attendeePW, moderatorPW 2–64 chars; meetingID 2–256 chars, no commas.
join — added role, excludeFromDashboard.

Updated in 2.5:

create — added meetingCameraCap, groups, disabledFeatures, meetingExpireIfNoUserJoinedInMinutes, meetingExpireWhenLastUserLeftInMinutes, preUploadedPresentationOverrideDefault; deprecated learningDashboardEnabled, breakoutRoomsEnabled, virtualBackgroundsDisabled. insertDocument endpoint introduced.

Updated in 2.6:

create — added notifyRecordingIsOn, presentationUploadExternalUrl, presentationUploadExternalDescription (≥2.6.9), recordFullDurationMedia (≥2.6.9), disabledFeaturesExclude (≥2.6.9), liveTranscription, presentation for disabledFeatures.
getRecordings — pagination via offset, limit.
join — added userdata-bbb_hide_presentation_on_join.

Updated in 2.7:

create — added preUploadedPresentation, preUploadedPresentationName, allowPromoteGuestToModerator (≥2.7.9).
disabledFeatures options: cameraAsContent, snapshotOfCurrentSlide, downloadPresentationOriginalFile, downloadPresentationConvertedToPdf, timer, errorRedirectUrl, userdata-bbb_fullaudio_bridge.
Added allowOverrideClientSettingsOnCreateCall, loginURL, pluginManifests.

Updated in 3.0:

create — added pluginManifestsFetchUrl, presentationConversionCacheEnabled, maxNumPages, multiUserWhiteboardEnabled, clientSettingsOverrideJsonUrl, sharedNotesEditor.
meetingLayout — added CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
disabledFeatures — added options infiniteWhiteboard, deleteChatMessage, editChatMessage, replyChatMessage, chatMessageReactions, raiseHand, userReactions, chatEmojiPicker, quizzes.
disabledFeatures — added clientSettingsOverride.
Removed: breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled (top-level create parameters — they are now toggled via disabledFeatures).
Added POST modules (under create request body): clientSettingsOverride, sharedNotesInitialContentJson / sharedNotesInitialContentJsonUrl.
join — added bot, enforceLayout, logoutURL, firstName, lastName, and userdata-bbb_default_layout, userdata-bbb_skip_echotest_if_previous_device, userdata-bbb_prefer_dark_theme, userdata-bbb_hide_notifications, userdata-bbb_hide_controls, userdata-bbb_initial_selected_tool, userdata-bbb_ask_for_feedback_on_logout.
Removed: defaultLayout (replaced by userdata-bbb_default_layout). Support for non-GET HTTP methods on join was removed.
New endpoints: sendChatMessage, getJoinUrl.
Renamed endpoint: /html5client/feedback → /api/feedback.
Removed endpoint: /html5client/check (replaced by the standard health presence checks).
Shared notes: blockNote editor + sharedNotesInitialContentJsonUrl (initial content fetched from a URL) and sharedNotesInitialContentJson POST module (initial content embedded directly in the request body).

Meetings

Create, join, end, inspect meetings.

Create a meeting

Creates a BigBlueButton meeting. The call is idempotent — calling it repeatedly with the same parameters returns SUCCESS without side effects. Empty meetings auto-expire after meetingExpireIfNoUserJoinedInMinutes.

Authorizations:

checksumQuery

query Parameters

name required	string [ 2 .. 64 ] characters Meeting name. 2–64 characters.
meetingID required	string [ 2 .. 256 ] characters Unique meeting identifier. 2–256 characters, no commas.
attendeePW required	string [ 2 .. 64 ] characters Password attendees must supply to join. 2–64 characters.
moderatorPW required	string [ 2 .. 64 ] characters Password moderators must supply to join. 2–64 characters.
welcome	string Welcome message shown on joining.
dialNumber	string Dial-in phone number for the conference.
voiceBridge	string^\d{5}$ 5-digit numeric voice conference bridge number.
maxParticipants	integer >= 0 Cap on concurrent participants (0 = unlimited).
logoutURL	string <uri> URL to which the user is redirected after logout.
record	boolean Start recording automatically.
autoStartRecording	boolean Start recording automatically (moderator can override).
allowStartStopRecording	boolean Allow moderators to start/stop recording.
moderatorOnlyMessage	string Message visible only to moderators.
webcamsOnlyForModerator	boolean Only moderators see all webcams.
logo	string <uri> URL of a logo to display.
bannerText	string
bannerColor	string^#[0-9A-Fa-f]{6}$ Hex background color for the banner.
copyright	string
muteOnStart	boolean
allowModsToUnmuteUsers	boolean
lockSettingsDisableCam	boolean
lockSettingsDisableMic	boolean
lockSettingsDisablePrivateChat	boolean
lockSettingsDisablePublicChat	boolean
lockSettingsDisableNotes	boolean
lockSettingsHideUserList	boolean
lockSettingsLockOnJoin	boolean
lockSettingsLockOnJoinConfigurable	boolean
guestPolicy	string Enum: "ALWAYS_ACCEPT" "ALWAYS_DENY" "ASK_MODERATOR" Guest access policy: `ALWAYS_ACCEPT` — guests join directly `ALWAYS_DENY` — guests must wait for moderator approval `ASK_MODERATOR` — prompt the moderator
meetingKeepEvents	boolean Keep events after the meeting ends.
endWhenNoModerator	boolean
endWhenNoModeratorDelayInMinutes	integer >= 0
meetingLayout	string Enum: "CUSTOM_LAYOUT" "SMART_LAYOUT" "PRESENTATION_FOCUS" "VIDEO_FOCUS" "CAMERAS_ONLY" "PARTICIPANTS_AND_CHAT_ONLY" "PRESENTATION_ONLY" "MEDIA_ONLY" Layout applied to the meeting. `CAMERAS_ONLY`, `PARTICIPANTS_AND_CHAT_ONLY`, `PRESENTATION_ONLY`, and `MEDIA_ONLY` were added in 3.0.
learningDashboardCleanupDelayInMinutes	integer >= 0
allowModsToEjectCameras	boolean
allowRequestsWithoutSession	boolean
userCameraCap	integer >= 0 Max simultaneous webcams per user.
meetingCameraCap	integer >= 0 Max webcams in the meeting.
groups	string JSON-encoded breakout-room groups.
disabledFeatures	string Comma-separated list of features to disable. Recognised options (3.0 unless noted): `breakoutRooms`, `learningDashboard`, `virtualBackgrounds`, `cameraAsContent`, `snapshotOfCurrentSlide`, `downloadPresentationOriginalFile`, `downloadPresentationConvertedToPdf`, `timer`, `liveTranscription`, `presentation`, `infiniteWhiteboard`, `deleteChatMessage`, `editChatMessage`, `replyChatMessage`, `chatMessageReactions`, `raiseHand`, `userReactions`, `chatEmojiPicker`, `quizzes`, `clientSettingsOverride`.
meetingExpireIfNoUserJoinedInMinutes	integer >= 0
meetingExpireWhenLastUserLeftInMinutes	integer >= 0
preUploadedPresentationOverrideDefault	boolean
preUploadedPresentation	string <uri> URL of a presentation to pre-upload.
preUploadedPresentationName	string
allowPromoteGuestToModerator	boolean
notifyRecordingIsOn	boolean
presentationUploadExternalUrl	string <uri> External upload tool URL (displayed as a button).
presentationUploadExternalDescription	string
recordFullDurationMedia	boolean Record full-duration media (≥2.6.9).
disabledFeaturesExclude	string Comma-separated features to exclude from `disabledFeatures` (≥2.6.9).
liveTranscription	string JSON live-transcription settings.
allowOverrideClientSettingsOnCreateCall	boolean Enable client settings override via POST body (≥2.7).
loginURL	string <uri>
pluginManifests	string JSON plugin manifests (≥2.7).
pluginManifestsFetchUrl	string <uri> URL from which plugin manifests JSON is fetched (3.0).
presentationConversionCacheEnabled	boolean Cache converted presentations on disk (3.0).
maxNumPages	integer >= 0 Maximum number of pages allowed in a pre-uploaded presentation (3.0).
multiUserWhiteboardEnabled	boolean Allow multiple users to edit the whiteboard simultaneously (3.0).
clientSettingsOverrideJsonUrl	string <uri> URL pointing to a JSON document that overrides the default `settings.yml` client settings for this meeting (3.0). Requires `allowOverrideClientSettingsOnCreateCall=true`.
sharedNotesEditor	string Default: "ethereal" Enum: "ethereal" "blockNote" Shared-notes editor to use (3.0). `ethereal` for the legacy Etherpad editor, or `blockNote` to use the BlockNote rich-text editor.
errorRedirectUrl	string <uri>
meta_endCallbackUrl	string <uri> Callback URL invoked when the meeting ends.
meta_analytics-callback-url	string <uri> POST callback URL receiving Learning Analytics JSON.
meta_bbb-recording-ready-url	string <uri> POST callback URL invoked when the recording is ready (JWT-signed).

Responses

Response samples

Content type

application/xml

Example

New meeting created

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>Test</meetingID>
  <internalMeetingID>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</internalMeetingID>
  <parentMeetingID>bbb-none</parentMeetingID>
  <attendeePW>ap</attendeePW>
  <moderatorPW>mp</moderatorPW>
  <createTime>1531155809613</createTime>
  <voiceBridge>70757</voiceBridge>
  <dialNumber>613-555-1234</dialNumber>
  <createDate>Mon Jul 09 17:03:29 UTC 2018</createDate>
  <hasUserJoined>false</hasUserJoined>
  <duration>0</duration>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
  <messageKey>duplicateWarning</messageKey>
  <message>This conference was already in existence and may currently be in progress.</message>
</response>

Create a meeting with POST modules (clientSettingsOverride, sharedNotes, ...)

POST variant of create. All query parameters accepted by the GET form are also accepted here; in addition, the request body can carry <modules> payloads introduced in 3.0:

<module name="clientSettingsOverride"> — JSON document that overrides the default settings.yml client settings for this meeting. Requires allowOverrideClientSettingsOnCreateCall=true either as a query parameter or in bbb-web.properties.
<module name="sharedNotesInitialContentJson"> — initial BlockNote document for the shared notes when sharedNotesEditor=blockNote. The payload must follow the structure documented in BlockNote. Equivalent to setting sharedNotesInitialContentJsonUrl to a URL whose contents are the same JSON structure.

The POST payload size must not exceed 2 MB.

Authorizations:

checksumQuery

query Parameters

name required	string [ 2 .. 64 ] characters Meeting name. 2–64 characters.
meetingID required	string [ 2 .. 256 ] characters Unique meeting identifier. 2–256 characters, no commas.
attendeePW required	string [ 2 .. 64 ] characters Password attendees must supply to join. 2–64 characters.
moderatorPW required	string [ 2 .. 64 ] characters Password moderators must supply to join. 2–64 characters.
allowOverrideClientSettingsOnCreateCall	boolean Required to be `true` to honour the `clientSettingsOverride` module (3.0).

Request Body schema: application/xml
optional

string

Responses

Request samples

Payload

Content type

application/xml

Example

Override client settings via the `clientSettingsOverride` module

<modules>
  <module name="clientSettingsOverride">
    <![CDATA[
      {"public":{"kurento":{"wsUrl":"wss://test.bigbluebutton.org/bbb-webrtc-sfu"},"media":{"sipjsHackViaWs":false},"app":{"appName":"Test","helpLink":"https://www.bigbluebutton.org","autoJoin":false,"askForConfirmationOnLeave":false,"userSettingsStorage":"localStorage","defaultSettings":{"application":{"overrideLocale":"en"}}}}}
    ]]>
  </module>
</modules>

Join a user to a meeting

Joins a user to the meeting specified by meetingID. By default (redirect=true) the call returns a redirect URL — the client should be redirected to it. Set redirect=false to receive the URL in an XML response.

As of 3.0, only the GET HTTP method is supported on this endpoint. The legacy defaultLayout parameter was removed and replaced by userdata-bbb_default_layout.

Authorizations:

checksumQuery

query Parameters

fullName required	string Display name of the joining user.
meetingID required	string [ 2 .. 256 ] characters Unique meeting identifier. 2–256 characters, no commas.
password required	string The moderator or attendee password, depending on context.
createTime	string Timestamp from the `create` response (used with `userID` for validation).
userID	string Required when using `createTime` to verify the join URL.
role	string Enum: "MODERATOR" "VIEWER" "ATTENDEE" Role for the joining user: `MODERATOR` — full permissions `VIEWER` — attendee (default; `ATTENDEE` is deprecated)
excludeFromDashboard	boolean Hide this user from the Learning Analytics dashboard.
redirect	boolean Default: true If `false`, return an XML body containing the join URL instead of issuing a redirect.
configToken	string References a config file in `/var/bigbluebutton/configs`, e.g. `myconfig.xml`.
guest	boolean Join as a guest.
bot	boolean Join as a bot user (3.0). Bots are excluded from participant counts and the Learning Analytics dashboard.
enforceLayout	string Enum: "CUSTOM_LAYOUT" "SMART_LAYOUT" "PRESENTATION_FOCUS" "VIDEO_FOCUS" "CAMERAS_ONLY" "PARTICIPANTS_AND_CHAT_ONLY" "PRESENTATION_ONLY" "MEDIA_ONLY" Force the joined user onto a specific layout regardless of their `userdata-bbb_default_layout` setting (3.0).
logoutURL	string <uri> URL the client should redirect to when the user logs out (3.0).
firstName	string First name component, displayed separately in the UI (3.0).
lastName	string Last name component, displayed separately in the UI (3.0).
userdata-bbb_hide_presentation_on_join	boolean Per-user override: hide presentation on join.
userdata-bbb_fullaudio_bridge	string Per-user override: full-audio bridge.
userdata-bbb_default_layout	string Per-user default layout, replacing the removed `defaultLayout` parameter (3.0). One of the same layout names accepted by `enforceLayout` / `meetingLayout`.
userdata-bbb_skip_echotest_if_previous_device	boolean Per-user override: skip the microphone echotest if the device was already tested (3.0).
userdata-bbb_prefer_dark_theme	boolean Per-user override: prefer the dark theme (3.0).
userdata-bbb_hide_notifications	boolean Per-user override: hide toast notifications (3.0).
userdata-bbb_hide_controls	boolean Per-user override: hide the on-screen presentation controls (3.0).
userdata-bbb_initial_selected_tool	string Per-user override: initial whiteboard tool selected on join (3.0).
userdata-bbb_ask_for_feedback_on_logout	boolean Per-user override: show the feedback form when the user logs out (3.0). Submissions go to the `/feedback` endpoint.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
  <meeting_id>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</meeting_id>
  <user_id>w_euxnssffnsbs</user_id>
  <auth_token>14mm5y3eurjw</auth_token>
  <session_token>ai1wqj8wb6s7rnk0</session_token>
  <url>https://yourserver.com/client/BigBlueButton.html?sessionToken=ai1wqj8wb6s7rnk0</url>
</response>

End a meeting

Forcibly ends a meeting and kicks all participants. The call is asynchronous — confirm completion via getMeetingInfo or isMeetingRunning a few seconds later.

Authorizations:

checksumQuery

query Parameters

meetingID required	string [ 2 .. 256 ] characters Unique meeting identifier. 2–256 characters, no commas.
moderatorPW required	string [ 2 .. 64 ] characters Password moderators must supply to join. 2–64 characters.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>sentEndMeetingRequest</messageKey>
  <message>A request to end the meeting was sent. Please wait a few seconds, and then use the getMeetingInfo or isMeetingRunning API calls to verify that it was ended.</message>
</response>

Get information about a meeting

Returns full meeting info, including the list of attendees and start/end times. If the meeting has breakout rooms, the response also includes breakoutRooms. If the meeting is a breakout room, the response includes breakout with the parent meeting ID.

Authorizations:

checksumQuery

query Parameters

meetingID

required

string [ 2 .. 256 ] characters

Unique meeting identifier. 2–256 characters, no commas.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <meetingName>Anton G's Room</meetingName>
  <meetingID>gbesu6dht08uobpislzqxsizjzihn87cmewqyacs</meetingID>
  <internalMeetingID>a0715c95000a2bcb90604ecc7097dbc94592c690-1715261728123</internalMeetingID>
  <createTime>1715261728123</createTime>
  <createDate>Thu May 09 13:35:28 UTC 2024</createDate>
  <voiceBridge>66052</voiceBridge>
  <dialNumber>613-555-1234</dialNumber>
  <running>true</running>
  <duration>0</duration>
  <hasUserJoined>true</hasUserJoined>
  <recording>true</recording>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
  <startTime>1715261728142</startTime>
  <endTime>0</endTime>
  <participantCount>1</participantCount>
  <moderatorCount>1</moderatorCount>
  <attendees>
    <attendee>
      <userID>w_ftcrsyuh44oj</userID>
      <fullName>Anton G</fullName>
      <role>MODERATOR</role>
      <isPresenter>true</isPresenter>
      <hasJoinedVoice>true</hasJoinedVoice>
      <hasVideo>true</hasVideo>
      <clientType>HTML5</clientType>
    </attendee>
  </attendees>
  <metadata>
    <bbb-origin-version>summit2024-6d8120x</bbb-origin-version>
    <bbb-origin-server-name>test30.bigbluebutton.org</bbb-origin-server-name>
  </metadata>
  <isBreakout>false</isBreakout>
</response>

Insert one or more documents into a running meeting

Adds one or more documents to a meeting already in progress. Sends a POST with an XML <modules> body whose <module name="presentation"> carries one <document> per slide.

Per-document attributes (downloadable, removable, url, filename, current) work the same as in create's pre-upload slide payload.

Authorizations:

checksumQuery

query Parameters

meetingID

required

string [ 2 .. 256 ] characters

Unique meeting identifier. 2–256 characters, no commas.

Request Body schema: application/xml
required

string

Responses

Request samples

Payload

Content type

application/xml

<modules>
  <module name="presentation">
    <document current="true" downloadable="true" url="https://example.com/sample.pdf" filename="sample.pdf"/>
    <document removable="false" name="sample.pdf">JVBERi0xLjQKJeLjz9MK...</document>
  </module>
</modules>

List all meetings on the server

Returns every meeting found on the server. Since BigBlueButton 0.80, no parameters are required.

Authorizations:

checksumQuery

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <meetings>
    <meeting>
      <meetingName>Demo Meeting</meetingName>
      <meetingID>Demo Meeting</meetingID>
      <internalMeetingID>183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531241258036</internalMeetingID>
      <createTime>1531241258036</createTime>
      <createDate>Tue Jul 10 16:47:38 UTC 2018</createDate>
      <voiceBridge>70066</voiceBridge>
      <dialNumber>613-555-1234</dialNumber>
      <attendeePW>ap</attendeePW>
      <moderatorPW>mp</moderatorPW>
      <running>false</running>
      <duration>0</duration>
      <hasUserJoined>false</hasUserJoined>
      <recording>false</recording>
      <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
      <startTime>1531241258074</startTime>
      <endTime>0</endTime>
      <participantCount>0</participantCount>
      <listenerCount>0</listenerCount>
      <voiceParticipantCount>0</voiceParticipantCount>
      <videoCount>0</videoCount>
      <maxUsers>0</maxUsers>
      <moderatorCount>0</moderatorCount>
      <attendees />
      <metadata />
      <isBreakout>false</isBreakout>
    </meeting>
  </meetings>
</response>

Generate a new /join URL for an existing user

Generates a new /join URL associated with the same user ID, so multiple sessions appear as the same user in the user list. Useful for hybrid environments (multiple screens) and for seamless device transfers (e.g. QR-code handoff).

Authorizations:

checksumQuery

query Parameters

sessionToken required	string Token from the existing session.
sessionName	string Label for the new session.
enforceLayout	string Force a specific layout for the new session.
userdata-bbb_client_title	string Per-session client title override.

Responses

Response samples

Content type

application/json

{"response": {"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://yourserver.com/bigbluebutton/api/join?&redirect=true&existingUserID=w_t18rn7uc1wjm&role=MODERATOR&userdata-bbb_client_title=Presentation+client&sessionName=Presentation+session&fullName=teacher%2B1&meetingID=random-7653737&enforceLayout=PRESENTATION_ONLY&checksum=135f230a2339b9485d91a3e87b1a22420ca57e8b"
}
}

Recordings

List, publish, update, delete recordings.

Get recordings (metadata)

Returns recordings available for playback. Pagination via offset / limit is supported since 2.6; when paginated, the response also includes totalElements (≥2.7).

Authorizations:

checksumQuery

query Parameters

meetingID	string Filter by meeting ID(s). Comma-separated for multiple.
recordID	string Filter by record ID(s). Comma-separated for multiple.
state	string Enum: "published" "unpublished" "any" "deleted" Filter by recording state.
meta_	string Filter by metadata. Pass any number of `meta_<name>=<value>` query parameters.
offset	integer >= 0 Pagination start (≥2.6).
limit	integer >= 1 Pagination size (≥2.6).

Responses

Response samples

Content type

application/xml

Example

success

<response>
  <returncode>SUCCESS</returncode>
  <recordings>
    <recording>
      <recordID>ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</recordID>
      <meetingID>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingID>
      <name>Fred's Room</name>
      <published>true</published>
      <state>published</state>
      <startTime>1530718721124</startTime>
      <endTime>1530718810456</endTime>
      <participants>3</participants>
      <playback>
        <format>
          <type>podcast</type>
          <url>https://demo.bigbluebutton.org/podcast/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/audio.ogg</url>
          <processingTime>0</processingTime>
          <length>0</length>
        </format>
        <format>
          <type>presentation</type>
          <url>https://demo.bigbluebutton.org/playback/presentation/2.0/playback.html?meetingId=ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</url>
          <processingTime>7177</processingTime>
          <length>0</length>
        </format>
      </playback>
    </recording>
  </recordings>
</response>

Publish or unpublish recordings

Publishes or unpublishes recordings for the given recordID (or comma-separated set of record IDs).

Authorizations:

checksumQuery

query Parameters

recordID required	string One or more record IDs (comma-separated).
publish required	boolean `true` to publish, `false` to unpublish.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <published>true</published>
</response>

Delete one or more recordings

Deletes recordings for the given recordID (or comma-separated set of record IDs).

Authorizations:

checksumQuery

query Parameters

recordID

required

string

One or more record IDs (comma-separated).

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <deleted>true</deleted>
</response>

Update metadata for one or more recordings

Updates metadata for the given recordID (or comma-separated set). Pass any number of meta_<name>=<value> query parameters to set or replace metadata fields. Available since 1.1.

Authorizations:

checksumQuery

query Parameters

recordID

required

string

One or more record IDs (comma-separated).

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <updated>true</updated>
</response>

List caption/subtitle tracks for a recording

Returns WebVTT track metadata (href, kind, lang, label, source) for a given recording. Useful for retrieving live or automatic captions for manual editing.

Source values: live, automatic, upload.

Authorizations:

checksumQuery

query Parameters

recordID

required

string

Recording ID.

Responses

Response samples

Content type

application/json

{"response": {"returncode": "SUCCESS",
"tracks": [{"href": "https://captions.example.com/textTrack/0ab39e419c9bcb63233168daefe390f232c71343/183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1554230749920/subtitles_en-US.vtt",
"kind": "subtitles",
"label": "English",
"lang": "en-US",
"source": "upload"
},
{"href": "https://captions.example.com/textTrack/95b62d1b762700b9d5366a9e71d5fcc5086f2723/183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1554230749920/subtitles_pt-BR.vtt",
"kind": "subtitles",
"label": "Brazil",
"lang": "pt-BR",
"source": "upload"
}
]
}
}

Upload or delete a caption/subtitle track

Uploads a subtitle or caption file to a recording. If a track with the same kind+lang already exists, it is replaced.

POST only. Query parameters carry checksum inputs; the subtitle file is uploaded in the request body as multipart/form-data and is not part of the checksum. Asynchronous — processing can take several minutes.

Authorizations:

checksumQuery

query Parameters

recordID required	string Recording ID.
kind required	string Enum: "captions" "subtitles" Track kind (`captions` or `subtitles`).
lang required	string RFC 5646 language tag, e.g. `en-US`, `pt-BR`.
label required	string Human-readable label shown in the subtitle picker.
content	string Alternative to file upload. The track payload encoded inline (e.g. base64) — provided when file upload isn't available.
content_base64	string <byte> Same as `content` but base64-encoded.

Request Body schema: multipart/form-data
optional

file	string <binary> Subtitle/caption file. Accepted formats: SRT (`application/x-subrip`), SSA/ASS, WebVTT (`text/vtt`). Omit to delete any existing track matching `kind` + `lang`.

Responses

Response samples

Content type

application/json

Example

success

{"response": {"messageKey": "upload_text_track_success",
"message": "Text track uploaded successfully",
"recordId": "baz",
"returncode": "SUCCESS"
}
}

Monitoring

Health and presence checks.

Check whether a meeting is currently running

Returns <running>true</running> if a user has joined.

Authorizations:

checksumQuery

query Parameters

meetingID

required

string [ 2 .. 256 ] characters

Unique meeting identifier. 2–256 characters, no commas.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <running>true</running>
</response>

Custom

Greenlight-style extensions (attendance analytics, MP4 export). Signed and dispatched via the standard checksum query parameter, but not part of upstream BBB core — availability depends on the build/deployment packaging.

Retrieve attendance data.

Returns JSON attendance data for one or more meetings. The response includes attendance records, poll data, talk time, emoji usage, and the public Learning Dashboard URL for each meeting.

Pass either internalMeetingID or meetingID, separated by commas. Do not mix the two — pick one identifier type per request.

Authorizations:

checksumQuery

query Parameters

internalMeetingID	string One or more internal meeting IDs (comma-separated).
meetingID	string One or more meeting IDs (comma-separated).

Responses

Response samples

Content type

application/json

{"response": {"returncode": "SUCCESS",
"meetings": [{"meetingID": "sample-meeting-id",
"internalMeetingID": "183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531241258036",
"name": "Demo Meeting",
"learningDashboardUrl": "https://yourserver.com/learning-dashboard/183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531241258036"
}
]
}
}

List all past meetings.

Returns JSON describing every past meeting stored on the server (meeting ID, internal meeting ID, start/end times, name). The returned IDs can be fed back into getAttendance to retrieve attendance data for a specific meeting.

Authorizations:

checksumQuery

Responses

Response samples

Content type

application/json

{"response": {"returncode": "SUCCESS",
"meetings": [{"meetingID": "sample-meeting-id",
"internalMeetingID": "183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531241258036",
"name": "Demo Meeting",
"startTime": 1531241258036,
"endTime": 1531244823042
}
]
}
}

Queue a recording for MP4 conversion.

Queues the given recording for MP4 processing. Optionally accepts an email address (notifications) and an mp4ReadyCallbackUrl that BBB will POST to once the MP4 has been produced.

Note: this endpoint can only be called once per recording, after the recording has been processed by the standard recording pipeline.

Authorizations:

checksumQuery

query Parameters

recordID required	string Recording ID to process.
email	string <email> Email address to notify when MP4 conversion completes.
mp4ReadyCallbackUrl	string <uri> HTTPS URL BBB will POST to once the MP4 file is ready.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>sentEndRecordingRequest</messageKey>
  <message>A request to convert the recording to MP4 was sent.</message>
</response>

Retrieve MP4 URL(s) for a processed recording.

Returns XML containing the URL(s) for the MP4 version of a recording. Only works after the recording has been successfully processed by processMP4.

Authorizations:

checksumQuery

query Parameters

recordID

required

string

Recording ID whose MP4 URL is requested.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <url>https://yourserver.com/podcast/recording-id.mp4</url>
</response>

Submit end-of-meeting feedback for a user.

Replaces the legacy /html5client/feedback endpoint introduced in 3.0. Accepts the per-user feedback that the BBB client submits when userdata-bbb_ask_for_feedback_on_logout=true is set on join.

Returns XML in the standard returncode envelope.

Authorizations:

checksumQuery

query Parameters

meetingID required	string ID of the meeting the feedback pertains to.
userID required	string ID of the user submitting feedback.
rating	integer [ 1 .. 5 ] Star rating, 1–5.
comment	string Free-text comment from the user.

Responses

Response samples

Content type

application/xml

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>feedbackSubmitted</messageKey>
  <message>Feedback submitted successfully.</message>
</response>

Chats

Send a public chat message

Sends a message to the public chat of a running meeting. Added in 3.0.

Authorizations:

checksumQuery

query Parameters

meetingID required	string [ 2 .. 256 ] characters Unique meeting identifier. 2–256 characters, no commas.
message required	string Message body.
userName	string Display name for the message sender.

Responses

Response samples

Content type

application/xml

<response>
    <returncode>SUCCESS</returncode>
    <messageKey></messageKey>
    <message></message>
</response>

BigBlueButton API (3.0)

Version history

Meetings

Create a meeting

Authorizations:

query Parameters

Responses

Response samples

Create a meeting with POST modules (clientSettingsOverride, sharedNotes, ...)

Authorizations:

query Parameters

Request Body schema: application/xmloptional

Responses

Request samples

Join a user to a meeting

Authorizations:

query Parameters

Responses

Response samples

End a meeting

Authorizations:

query Parameters

Responses

Response samples

Get information about a meeting

Authorizations:

query Parameters

Responses

Response samples

Insert one or more documents into a running meeting

Authorizations:

query Parameters

Request Body schema: application/xmlrequired

Responses

Request samples

List all meetings on the server

Authorizations:

Responses

Response samples

Generate a new /join URL for an existing user

Authorizations:

query Parameters

Responses

Response samples

Recordings

Get recordings (metadata)

Authorizations:

query Parameters

Responses

Response samples

Publish or unpublish recordings

Authorizations:

query Parameters

Responses

Response samples

Delete one or more recordings

Authorizations:

query Parameters

Responses

Response samples

Update metadata for one or more recordings

Authorizations:

query Parameters

Responses

Response samples

List caption/subtitle tracks for a recording

Authorizations:

query Parameters

Responses

Response samples

Upload or delete a caption/subtitle track

Authorizations:

query Parameters

Request Body schema: multipart/form-dataoptional

Responses

Response samples

Monitoring

Check whether a meeting is currently running

Authorizations:

query Parameters

Request Body schema: application/xml
optional

Request Body schema: application/xml
required

Request Body schema: multipart/form-data
optional