You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.
create – Create Meeting
The create endpoint provisions a new meeting on the BigBlueButton server. If a meeting with the same meetingID already exists, the server returns the existing meeting data instead of creating a duplicate (idempotent behaviour).
Endpoint
POST GET
https://api-guide.bbbserver.com/bigbluebutton/api/create?<parameters>&checksum=replace-with-checksum Required Parameters
| Parameter | Type | Description |
|---|---|---|
meetingID | String | Unique meeting identifier (2 to 256 characters, no commas). |
name | String | Display name of the meeting (2 to 256 characters). Required since BBB 2.4. |
Optional Parameters
General
| Parameter | Type | Default | Description |
|---|---|---|---|
attendeePW Deprecated | String | (auto) | Password for attendee access. Deprecated since BBB 3.0 — generated automatically. |
moderatorPW Deprecated | String | (auto) | Password for moderator access. Deprecated since BBB 3.0 — generated automatically. |
welcome | String | — | Welcome message shown in the session details dialog. Supports placeholders: %%CONFNAME%%, %%DIALNUM%%, %%CONFNUM%%, %%SERVERURL%%. |
moderatorOnlyMessage | String | — | Message shown only to moderators in the session details dialog. |
dialNumber | String | — | Dial-in number for phone-based participation. |
voiceBridge | String | (auto) | Five random digits (may start with 0, e.g. 07382), generated automatically. Must be unique per meeting. |
maxParticipants | Number | 0 (unlimited) | Maximum number of participants. On bbbserver.de this value is used for capacity reservation (see bbbserver.de notes below). |
duration | Number | 0 (unlimited) | Maximum duration in minutes. In standard BBB the meeting ends automatically when the time is up. On bbbserver.de this is used only for capacity planning (see bbbserver.de notes below). |
logoutURL | String | — | URL the user is redirected to after logout. |
loginURL | String | — | URL made accessible to users during the meeting. BBB 3.0+ |
record | Boolean | false | Enable recording of media and events. |
autoStartRecording | Boolean | false | Recording starts automatically when the first person joins. |
allowStartStopRecording | Boolean | true | Allow users to manually start and stop the recording. |
recordFullDurationMedia | Boolean | false | Record media for the entire meeting duration. BBB 2.6.9+ |
muteOnStart | Boolean | true | Mute all participants when they join. |
guestPolicy | Enum | ALWAYS_ACCEPT | Guest policy: ALWAYS_ACCEPT, ALWAYS_DENY, or ASK_MODERATOR. |
webVoice Deprecated Removed in 4.0 | String | (= voiceBridge) | Obsolete. Selected a separate voice conference for the old Flash client and has no effect since BBB 2.3; the value always falls back to voiceBridge. |
meetingEndedURL | String | — | Server-to-server callback URL invoked when the meeting ends. Unlike meta_endCallbackUrl, this stays server-side and is not propagated to the client or recording metadata. The URL is called unchanged. BBB 2.2+ |
logoutTimer Undocumented Removed in 4.0 | Number | 0 (disabled) | Intended as a timeout in minutes before automatic logout. The value is stored by bbb-web but never reaches the client, so it has no effect. |
Layout & Appearance
| Parameter | Type | Default | Description |
|---|---|---|---|
meetingLayout | Enum | CUSTOM_LAYOUT | Default layout. Possible values: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY. |
logo | String | — | URL of a logo image displayed above the participant list. BBB 2.4+ |
bannerText | String | — | Banner text shown in the client. BBB 2.0+ |
bannerColor | String | — | Banner background colour as a hex value, e.g. #FF0000. BBB 2.0+ |
darklogo | String | — | URL of a logo image for dark mode. BBB 3.0+ |
copyright Removed in 4.0 | String | — | Intended to set the copyright text of the client. The value is stored but not passed on to the client, so it has no visible effect. To change the copyright text, override public.app.copyright via clientSettingsOverride. |
Permissions & Lock Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
webcamsOnlyForModerator | Boolean | false | Webcams visible only to moderators. |
allowModsToUnmuteUsers | Boolean | false | Allow moderators to unmute other users. BBB 2.2+ |
allowModsToEjectCameras | Boolean | false | Allow moderators to close other users' cameras. BBB 2.4+ |
allowPromoteGuestToModerator | Boolean | false | Allow promoting guests to moderator role. BBB 2.7.9+ |
lockSettingsDisableCam | Boolean | false | Lock camera sharing for attendees. BBB 2.2+ |
lockSettingsDisableMic | Boolean | false | Lock microphone for attendees (listen only). BBB 2.2+ |
lockSettingsDisablePrivateChat | Boolean | false | Lock private chat for attendees. BBB 2.2+ |
lockSettingsDisablePublicChat | Boolean | false | Lock public chat for attendees. BBB 2.2+ |
lockSettingsDisableNotes | Boolean | false | Lock shared notes for attendees. BBB 2.5+ The singular alias lockSettingsDisableNote is still accepted but deprecated (removed in BBB 4.0). |
lockSettingsHideUserList | Boolean | false | Hide participant list from viewers. BBB 2.2+ |
lockSettingsHideViewersCursor | Boolean | false | Hide other viewers' cursors on the whiteboard. BBB 2.5+ |
lockSettingsHideViewersAnnotation | Boolean | false | Hide other viewers' whiteboard annotations. BBB 2.7+ |
lockSettingsLockOnJoin | Boolean | true | Apply lock settings immediately when a user joins. BBB 2.2+ |
lockSettingsLockOnJoinConfigurable | Boolean | false | Enable the lockSettingsLockOnJoin setting to be applied. BBB 2.2+ |
Webcam
| Parameter | Type | Default | Description |
|---|---|---|---|
userCameraCap | Number | 3 | Maximum number of simultaneous webcams per user. BBB 2.4.5+ |
meetingCameraCap | Number | 0 (unlimited) | Maximum number of simultaneous webcams in the meeting. BBB 2.5+ |
maxPinnedCameras | Number | 3 | Maximum number of pinned webcams. BBB 2.6+ |
Disabling Features
| Parameter | Type | Default | Description |
|---|---|---|---|
disabledFeatures | String | — | Comma-separated list of features to disable. BBB 2.5+ |
disabledFeaturesExclude | String | — | Comma-separated list of features to re-enable for this meeting (overrides server-side defaults). BBB 2.6.9+ |
Available values for disabledFeatures:
| Value | Description |
|---|---|
breakoutRooms | Breakout rooms |
captions Deprecated | Typed captions. Has no effect since BBB 3.0 (typed captions moved to a plugin); use liveTranscription to disable automatic transcription. |
chat | Public and private chat |
privateChat | Private chat only |
deleteChatMessage | Delete chat messages BBB 3.0+ |
editChatMessage | Edit chat messages BBB 3.0+ |
replyChatMessage | Reply to chat messages BBB 3.0+ |
chatMessageReactions | Reactions on chat messages BBB 3.0+ |
chatEmojiPicker | Emoji picker in chat BBB 3.0.9+ |
downloadPresentationWithAnnotations | Download annotated presentation |
downloadPresentationConvertedToPdf | Download converted presentation |
downloadPresentationOriginalFile | Download original presentation file |
snapshotOfCurrentSlide | Snapshot of the current slide |
externalVideos | Share external video |
importPresentationWithAnnotationsFromBreakoutRooms | Import presentation from breakout rooms |
importSharedNotesFromBreakoutRooms | Import shared notes from breakout rooms |
layouts Removed in 4.0 | Layout selection (default layout only) |
learningDashboard | Learning analytics dashboard |
learningDashboardDownloadSessionData | Download dashboard session data |
polls | Polls |
screenshare | Screen sharing |
sharedNotes | Shared notes |
virtualBackgrounds | Virtual backgrounds |
customVirtualBackgrounds | Upload custom virtual backgrounds |
liveTranscription | Live transcription |
presentation | Presentation |
cameraAsContent | Camera as content |
timer | Timer |
infiniteWhiteboard | Infinite whiteboard BBB 3.0+ |
raiseHand | Raise hand BBB 3.0.7+ |
userReactions | User reactions BBB 3.0.8+ |
reactions | Emoji status reactions (different from userReactions) BBB 2.7+ |
quizzes | Quizzes BBB 3.0.11+ |
plugins | Plugins BBB 3.0.25+ |
Meeting Lifecycle
| Parameter | Type | Default | Description |
|---|---|---|---|
endWhenNoModerator | Boolean | false | Automatically end the meeting when no moderator is present. BBB 2.3+ |
endWhenNoModeratorDelayInMinutes | Number | 1 | Delay in minutes before automatic termination when no moderator is present. BBB 2.3+ |
meetingExpireIfNoUserJoinedInMinutes | Number | 5 | End the meeting if nobody joins within this many minutes. BBB 2.5+ |
meetingExpireWhenLastUserLeftInMinutes | Number | 1 | End the meeting X minutes after the last user leaves. 0 = disabled. BBB 2.5+ |
meetingKeepEvents | Boolean | false | Keep events even if the meeting is not being recorded. BBB 2.3+ |
learningDashboardCleanupDelayInMinutes | Number | 2 | Delay before deleting the learning analytics dashboard. BBB 2.4+ |
allowRequestsWithoutSession | Boolean | false | Allow joining without a session cookie. BBB 2.4.3+ |
Presentation
| Parameter | Type | Default | Description |
|---|---|---|---|
preUploadedPresentation | String | — | URL of a presentation file to pre-upload. BBB 2.7.2+ |
preUploadedPresentationName | String | — | Name for the pre-uploaded presentation. BBB 2.7.2+ |
preUploadedPresentationOverrideDefault | Boolean | true | Suppress the default presentation (default.pdf). BBB 2.5+ |
maxNumPages | Number | 200 | Maximum number of pages per presentation. BBB 3.0.2+ |
presentationUploadExternalUrl | String | — | URL of an external file picker application. BBB 2.6+ |
presentationUploadExternalDescription | String | — | Description for the external upload application. BBB 2.6+ |
presentationConversionCacheEnabled | Boolean | — | Enable presentation cache when using S3 storage. BBB 3.0.2+ |
Shared Notes
| Parameter | Type | Default | Description |
|---|---|---|---|
sharedNotesEditor Removed in 4.0 | String | etherpad | Editor used for the shared notes: blockNote or etherpad. The initial content parameters below only work with blockNote. BBB 3.0.25+ |
sharedNotesInitialContentJsonUrl | String | — | HTTPS URL from which the initial content of the shared notes is fetched (BlockNote JSON document). Capped by maxSharedNotesInitialContentUrlPayloadSize (default 1024 KiB) with a 6-second timeout; violations silently result in empty notes. BBB 3.0.25+ |
sharedNotesInitialContentMarkdown | String | — | Raw Markdown used as the initial content of the shared notes. sharedNotesInitialContentMarkdownUrl takes precedence over this value. BBB 3.0.33+ |
sharedNotesInitialContentMarkdownUrl | String | — | HTTPS URL from which Markdown for the initial content of the shared notes is fetched. Takes precedence over the inline parameter and the POST module. BBB 3.0.33+ |
Recording
| Parameter | Type | Default | Description |
|---|---|---|---|
notifyRecordingIsOn | Boolean | false | Show a modal dialog for recording consent. BBB 2.6+ |
notifyRecordingAppend | String | — | Optional plain text appended to the recording notification dialog. Only shown with notifyRecordingIsOn=true; HTML is displayed as text. BBB 3.0.36+ |
Whiteboard
| Parameter | Type | Default | Description |
|---|---|---|---|
multiUserWhiteboardEnabled | Boolean | — | Automatically enable whiteboard access for all users. Defaults to true in breakout rooms. BBB 3.0.20+ |
Plugins
| Parameter | Type | Default | Description |
|---|---|---|---|
pluginManifests | JSON | — | List of plugin manifests for the session. BBB 3.0+ |
pluginManifestsFetchUrl | String | — | URL of a JSON file containing plugin manifest URLs. BBB 3.0.8+ |
Breakout Rooms
The parameters isBreakout, parentMeetingID, sequence and freeJoin describe a breakout room and are only used when the breakout room itself is created (BigBlueButton does this internally). The other parameters in this table are set on the parent meeting and apply to its breakout rooms.
| Parameter | Type | Default | Description |
|---|---|---|---|
isBreakout | Boolean | — | Must be true for breakout rooms. |
parentMeetingID | String | — | Meeting ID of the parent meeting (required for breakout rooms). |
sequence | Number | — | Sequence number of the breakout room (required for breakout rooms). |
freeJoin | Boolean | — | Allow participants to choose their breakout room freely. |
breakoutRoomsPrivateChatEnabled | Boolean | true | Enable private chat in breakout rooms. |
breakoutRoomsRecord | Boolean | false | Record breakout rooms. |
breakoutRoomsCaptureSlides | Boolean | false | Capture slides from breakout rooms when they end. |
breakoutRoomsCaptureNotes | Boolean | false | Capture notes from breakout rooms when they end. |
breakoutRoomsCaptureSlidesFilename | String | — | Filename for captured slides. |
breakoutRoomsCaptureNotesFilename | String | — | Filename for captured notes. |
groups | JSON | — | Predefined group assignments as a JSON array. |
Format for groups:
[
{"id": "1", "name": "Group A", "roster": ["userId1", "userId2"]},
{"id": "2", "name": "Group B", "roster": ["userId3"]},
{"id": "3", "roster": []}
] Client Settings Override
| Parameter | Type | Default | Description |
|---|---|---|---|
allowOverrideClientSettingsOnCreateCall | Boolean | false | Server setting in bbb-web.properties (not a create parameter) that enables the clientSettingsOverride module in the POST body. BBB 3.0+ |
clientSettingsOverride | JSON | — | Overrides client settings from settings.yml. Only accepted as an XML module in an application/xml POST body – not as a query or form parameter. BBB 3.0+ |
clientSettingsOverrideJsonUrl | String | — | URL of a JSON file with client setting overrides. Works with plain GET requests, needs no server-side setting and takes precedence over the clientSettingsOverride module. BBB 3.0.25+ |
The clientSettingsOverride parameter is disabled by default for security reasons. Its values take higher priority than server-side configuration, and the POST body is not protected by the checksum.
Example as XML in the POST body:
<modules>
<module name="clientSettingsOverride">
<![CDATA[
{
"public": {
"app": {
"clientTitle": "My Conference",
"helpLink": "https://api-guide.bbbserver.com/help"
}
}
}
]]>
</module>
</modules> Bridges
| Parameter | Type | Default | Description |
|---|---|---|---|
cameraBridge | String | bbb-webrtc-sfu | Media bridge used for webcam streams: bbb-webrtc-sfu or livekit. BBB 3.0+ |
screenShareBridge | String | bbb-webrtc-sfu | Media bridge used for screen sharing: bbb-webrtc-sfu or livekit. BBB 3.0+ |
audioBridge | String | bbb-webrtc-sfu | Media bridge used for audio: bbb-webrtc-sfu, livekit or freeswitch. BBB 3.0+ |
These parameters override the server-wide bridge settings for a single meeting.
Meta Parameters
Arbitrary metadata can be passed as meta_<key>=<value>. Some meta parameters have special meanings:
| Meta Parameter | Description |
|---|---|
meta_endCallbackUrl | URL for a GET callback when the meeting ends. Parameters: meetingID, recordingmarks. |
meta_bbb-recording-ready-url | URL for a POST callback when the recording is ready (JWT-signed). |
meta_analytics-callback-url | URL for a POST callback with analytics data at meeting end (JSON). |
meta_bbb-anonymize-chat | Anonymize chat senders in recordings (attendees only). |
meta_bbb-anonymize-chat-moderators | Anonymize chat senders in recordings (including moderators). |
In addition to meta_* parameters, plugin_* parameters are also supported. These are processed as plugin metadata and can replace placeholders in plugin manifest URLs. BBB 3.0.10+
Example Request
GET https://api-guide.bbbserver.com/bigbluebutton/api/create?name=Demo&meetingID=replace-with-meeting-id&attendeePW=replace-with-password&moderatorPW=replace-with-password&checksum=replace-with-checksum Example Response
<response>
<returncode>SUCCESS</returncode>
<meetingID>replace-with-meeting-id</meetingID>
<internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
<parentMeetingID>bbb-none</parentMeetingID>
<attendeePW>replace-with-password</attendeePW>
<moderatorPW>replace-with-password</moderatorPW>
<createTime>1715261728123</createTime>
<voiceBridge>70066</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
<hasUserJoined>false</hasUserJoined>
<duration>0</duration>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<messageKey></messageKey>
<message></message>
</response> If a meeting with the same ID already exists, the response includes a duplicate warning:
<response>
<returncode>SUCCESS</returncode>
<meetingID>replace-with-meeting-id</meetingID>
<!-- ... same fields ... -->
<messageKey>duplicateWarning</messageKey>
<message>This conference was already in existence...</message>
</response> Uploading Presentations via POST Body
Presentations can be submitted as an XML body with the POST request:
<modules>
<module name="presentation">
<document url="https://api-guide.bbbserver.com/files/slides.pdf" filename="slides.pdf"
downloadable="true" removable="false" current="true"/>
<document url="https://api-guide.bbbserver.com/files/extras.pdf" filename="extras.pdf"/>
<document name="inline.pdf">
JVBERi0xLjQK... (Base64-encoded content)
</document>
</module>
</modules> Attributes per <document> element:
| Attribute | Type | Default | Description |
|---|---|---|---|
url | String | — | URL of the external file. |
filename | String | — | Filename including the extension. Required when the URL path does not end in a filename with an extension; otherwise the document is skipped. |
name | String | — | Name for Base64-embedded documents. |
downloadable | Boolean | false | Allow users to download the presentation. |
removable | Boolean | true | Allow users to remove the presentation. |
current | Boolean | — | This presentation is loaded first. |
When multiple documents are provided, the first one is loaded in the client while the remaining ones are converted in the background.
bbbserver.de Notes
Additional Parameter
| Parameter | Type | Default | Description |
|---|---|---|---|
deactivateBbbserverDefaultChatTexts | Boolean | false | When set to false (default), bbbserver.de automatically inserts chat texts (dial-in numbers, hosting notice). Your own welcome and moderatorOnlyMessage texts are appended after these. Set to true to suppress the bbbserver.de texts (white-labelling). |
Capacity Reservation
On bbbserver.de, the maxParticipants and duration parameters have a special meaning and behave differently from standard BigBlueButton.
When creating a meeting, bbbserver.de reserves hardware capacity:
- The specified number of participants is guaranteed and reserved on a server for the specified duration.
- The reserved capacity is deducted from your booked quota of simultaneous connections.
- If not specified, defaults apply: 5 participants and 60 minutes (configurable in the admin panel under Integrations & API → Integration API).
- After the duration expires, the meeting continues to run, but capacity is no longer reserved. bbbserver.de may end the meeting automatically if a new meeting requires the capacity.
- The
durationparameter does not terminate meetings. Unlike standard BBB, you must send anendAPI call to end a meeting after a certain time.
Since BBB 3.0, the attendeePW and moderatorPW parameters are deprecated. Use the role parameter on the join endpoint instead to assign roles.
Frequently Asked Questions
duplicateWarning message key to indicate this.role parameter on the join endpoint to assign attendee or moderator roles.modules/module element with document entries. Each document can reference an external URL or contain Base64-encoded file data.meta_endCallbackUrl is a meta parameter that may be propagated to the client and recording metadata. meetingEndedURL is a server-side callback that stays internal and is not exposed to clients, so it is the recommended option for URLs that contain secret tokens.maxParticipants and duration values. The reserved slots are deducted from your concurrent connection quota. After the duration expires the meeting continues but is no longer protected from being ended if capacity is needed elsewhere.allowOverrideClientSettingsOnCreateCall to true and passing a clientSettingsOverride JSON in the POST body. This is disabled by default for security reasons since the POST body is not covered by the checksum.