Chapter 1

API Overview

The BigBlueButton API is an HTTP-based interface that allows external applications — such as learning management systems, web portals, and custom integrations — to programmatically create, control, and monitor meetings. All API calls are secured using a checksum mechanism based on a shared secret.

How the API Works

The BBB API follows a simple request-response model. You send an HTTPS request to a specific endpoint on your BigBlueButton server, and the server responds with an XML document indicating success or failure.

  • Protocol: HTTPS (GET or POST)
  • Base URL: https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash>
  • Response format: XML (with a few exceptions that return JSON)
  • Authentication: Shared-secret-based checksum (no OAuth, no API key)

Endpoint Categories

The API endpoints are organized into the following categories:

Category Endpoints Description
Administration create, join, end Create, join, and end meetings
Monitoring isMeetingRunning, getMeetings, getMeetingInfo Monitor running meetings
Recordings getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack Manage meeting recordings
Webhooks hooks/create, hooks/list, hooks/destroy Real-time event notifications
Messaging sendChatMessage Send chat messages BBB 3.0+
Session getJoinUrl, feedback Session management BBB 3.0+

HTTP Methods

Most endpoints accept both GET and POST requests. When using POST, note that the checksum is calculated from the URL query string, not from the request body. The POST body can carry additional data such as presentation XML or client settings overrides.

Even when sending a POST request, the checksum must be computed from the query string parameters in the URL. The body content is not included in the checksum calculation.

Response Format

Every API response contains at least the following fields: 

<response>
  <returncode>SUCCESS</returncode>
  <!-- or -->
  <returncode>FAILED</returncode>
  <messageKey>errorKey</messageKey>
  <message>Human-readable error message</message>
</response>
Field Description
returncode Always SUCCESS or FAILED
messageKey Machine-readable error code (only present on errors or warnings)
message Human-readable description of the error or warning

API Versioning

The BigBlueButton API does not use traditional URL-based versioning (no /v1/, /v2/ paths). Instead, new parameters are added in a backward-compatible manner, and deprecated parameters are marked accordingly but not immediately removed.

BBB Version Notable API Changes
2.2 Lock settings, allowModsToUnmuteUsers
2.4 logo, meetingLayout, allowModsToEjectCameras, Learning Dashboard
2.5 disabledFeatures, SHA-384/SHA-512 support, webhook eventID filter
2.6 notifyRecordingIsOn, presentationUploadExternalUrl, dark mode
2.7 preUploadedPresentation (single URL), recording pagination
3.0 sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role replaces password on join

Undocumented Endpoints

The following endpoints exist in the BigBlueButton source code but are not covered in the official documentation. They are used internally and may change without notice.

Endpoint Method Description Status
/api/stuns GET POST Returns STUN/TURN server configuration for WebRTC connections Undocumented
/api/signOut GET POST End session / sign out user Undocumented
/api/guestWait GET Query lobby status for guests waiting for moderator approval Undocumented
/api/getSessions GET POST Retrieve session information Undocumented
/api/learningDashboard GET POST Retrieve learning analytics data Undocumented

GraphQL Mutations (In-Meeting Actions)

Since BBB 3.0, most real-time actions within a meeting are handled through GraphQL mutations over WebSocket. These are used internally by the BBB HTML5 client and are not part of the classic REST API.

Category Count Examples
Chat 9 chatSendMessage, chatDeleteMessage, chatEditMessage
User Management 26 userSetMuted, userSetRole, userEjectFromMeeting
Presentation 11 presentationSetCurrent, presentationSetPage
Meeting Control 8 meetingEnd, meetingRecordingSetStatus
Breakout Rooms 7 breakoutRoomCreate, breakoutRoomEndAll
Polls 4 pollCreate, pollSubmitUserVote, pollPublishResult
Timer 8 timerStart, timerStop, timerReset
Plugins 8 pluginDataChannelPushEntry, pluginPersistEvent

The GraphQL layer is intended for internal client use and does not provide a stable public API. Mutations and their parameters may change between BBB versions without notice.

Prerequisites

Before you can start using the BigBlueButton API, make sure you have the following in place:

A running BigBlueButton server (version 3.0 recommended)

The shared secret (also called "security salt"), configured in /etc/bigbluebutton/bbb-web.properties

HTTPS access to the server

A server-side application that generates the API calls — the shared secret must never be exposed on the client side

Never expose the shared secret in client-side code (JavaScript, mobile apps). All API calls must be generated server-side to prevent unauthorized access to your BigBlueButton server.

bbbserver.de — IntegrationAPI

Your API URL and shared secret are available in the bbbserver admin panel under Customer Settings → IntegrationAPI. The IntegrationAPI can be enabled or disabled from there.

Plugin Compatibility

The following platforms work out of the box — simply enter the API URL and shared secret:

  • Moodle (BigBlueButtonBN)
  • ILIAS
  • Nextcloud
  • WordPress
  • Greenlight

Differences from the Standard API

Topic Detail
maxParticipants / duration Used for capacity reservation, not just as limits. Defaults when not specified: 5 participants, 60 minutes.
duration behavior Does NOT automatically end meetings — used for capacity planning only.
Extra parameter deactivateBbbserverDefaultChatTexts — for white-labeling purposes.
Unavailable endpoints updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks
Webhooks Meeting-specific only, with privacy obfuscation.
Rate limits No rate limits on the IntegrationAPI.

In addition to the IntegrationAPI, bbbserver.de offers a separate System API with platform-specific features such as account management and usage statistics. The System API is not BBB-compatible and is not covered in this guide.

Frequently Asked Questions

The API uses a shared-secret-based checksum mechanism. Each request must include a checksum parameter that is calculated by hashing the API call name, the query string, and the shared secret. There is no OAuth or API key authentication.

The standard response format is XML. A few specific endpoints may return JSON, but the vast majority of API calls return XML documents with a returncode field indicating SUCCESS or FAILED.

No, the BigBlueButton API does not use URL-based versioning. New parameters are added in a backward-compatible way, and deprecated parameters are marked but not immediately removed. You should always check the changelog for your BBB version.

No. The GraphQL layer is designed for internal use by the BBB HTML5 client. It does not provide a stable public API, and mutations may change between versions without notice. Use the REST API for all external integrations.

The bbbserver.de IntegrationAPI is a proxy that fully replicates the standard BBB API. External applications connect to it as if communicating with a single BBB server. The main differences are capacity reservation via maxParticipants/duration, a few unavailable endpoints, and meeting-specific webhook restrictions.

BigBlueButton 2.5 and later supports SHA-256, SHA-384, and SHA-512 for checksum calculation. Earlier versions use SHA-1 or SHA-256. It is recommended to use SHA-256 or higher for security reasons.