API version: 4.x latest 3.x

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.

Chapter 3 GET POST

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.
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+

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
breakoutRoomsBreakout rooms
captions DeprecatedTyped captions. Has no effect since BBB 3.0 (typed captions moved to a plugin); use liveTranscription to disable automatic transcription.
chatPublic and private chat
privateChatPrivate chat only
deleteChatMessageDelete chat messages BBB 3.0+
editChatMessageEdit chat messages BBB 3.0+
replyChatMessageReply to chat messages BBB 3.0+
chatMessageReactionsReactions on chat messages BBB 3.0+
chatEmojiPickerEmoji picker in chat BBB 3.0.9+
downloadPresentationWithAnnotationsDownload annotated presentation
downloadPresentationConvertedToPdfDownload converted presentation
downloadPresentationOriginalFileDownload original presentation file
snapshotOfCurrentSlideSnapshot of the current slide
externalVideosShare external video
importPresentationWithAnnotationsFromBreakoutRoomsImport presentation from breakout rooms
importSharedNotesFromBreakoutRoomsImport shared notes from breakout rooms
layouts Removed in 4.0Layout selection (default layout only)
learningDashboardLearning analytics dashboard
learningDashboardDownloadSessionDataDownload dashboard session data
pollsPolls
screenshareScreen sharing
sharedNotesShared notes
virtualBackgroundsVirtual backgrounds
customVirtualBackgroundsUpload custom virtual backgrounds
liveTranscriptionLive transcription
presentationPresentation
cameraAsContentCamera as content
timerTimer
infiniteWhiteboardInfinite whiteboard BBB 3.0+
raiseHandRaise hand BBB 3.0.7+
userReactionsUser reactions BBB 3.0.8+
reactionsEmoji status reactions (different from userReactions) BBB 2.7+
quizzesQuizzes BBB 3.0.11+
pluginsPlugins 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 duration parameter does not terminate meetings. Unlike standard BBB, you must send an end API 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

The server returns the data of the existing meeting instead of creating a new one. The response includes a duplicateWarning message key to indicate this.

No. Since BBB 3.0 these passwords are deprecated and generated automatically. Use the role parameter on the join endpoint to assign attendee or moderator roles.

Send a POST request with an XML body containing a 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.

When you create a meeting, bbbserver.de reserves hardware capacity based on the 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.

Yes, by setting 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.