API Reference
Overview
This document describes the BigBlueButton application programming interface (API).
For developers, this API enables you to
- create meetings
- join meetings
- end meetings
- insert documents
- get recordings for past meetings (and delete them)
- upload closed caption files for meetings
- send a public chat message
To make an API call to your BigBlueButton server, your application makes HTTPS requests to the BigBlueButton server API endpoint (usually the server's hostname followed by /bigbluebutton/api
). All API calls must include checksum computed with a secret shared with the BigBlueButton server.
The BigBlueButton server returns an XML response to all API calls.
Updates to API in BigBlueButton
Updated in 0.9.0:
- join -
configToken
can now reference a file in/var/bigbluebutton/configs
, such asmyconfig.xml
. - create - Added three parameters:
moderatorOnlyMessage
to display message only visible to moderators andautoStartRecording
/allowStartStopRecording
to provide finer control over recordings.
Updated in 1.0:
- getMeetings - Added fields on the returned XML
- getMeetingInfo - Added fields on the returned XML and deprecated parameters
- getRecordings - Added meta parameter and state parameter to filter returned results
Updated in 1.1:
- create - Added fields on the returned XML
- getMeetings - Added fields on the returned XML
- getMeetingInfo - Added fields on the returned XML
- getRecordings - Returns an XML block with thumbnails from the slides as well as a
<participants>N</participants>
element with number of participants who attend the meeting. - updateRecordings - Meta parameters can be edited
Updated in 2.0:
- create - Added
bannerText
,bannerColor
,logo
,copyright
, andmuteOnStart
. - getMeetings - Now returns all the fields in getMeetingInfo.
- getMeetingInfo - Added
<client>
field to return client type (FLASH, or HTML5).
Updated in 2.2:
- create - Added
endWhenNoModerator
. - getRecordingTextTracks - Get a list of the caption/subtitle files currently available for a recording.
- putRecordingTextTrack - Upload a caption or subtitle file to add it to the recording. If there is any existing track with the same values for kind and lang, it will be replaced.
Updated in 2.3:
- create - Renamed
keepEvents
tomeetingKeepEvents
, removedjoinViaHtml5
, addedendWhenNoModeratorDelayInMinutes
. - getDefaultConfigXML obsolete, not used in HTML5 client.
- setConfigXML obsolete, not used in HTML5 client.
Updated in 2.4:
- getDefaultConfigXML Removed, not used in HTML5 client.
- setConfigXML Removed, not used in HTML5 client.
- create
- Added
meetingLayout
,learningDashboardEnabled
,learningDashboardCleanupDelayInMinutes
,allowModsToEjectCameras
,virtualBackgroundsDisabled
,allowRequestsWithoutSession
,userCameraCap
. name
,attendeePW
, andmoderatorPW
must be between 2 and 64 characters longmeetingID
must be between 2 and 256 characters long and cannot contain commas
- Added
- join - Added
role
,excludeFromDashboard
.
Updated in 2.5:
-
create - Added:
meetingCameraCap
,groups
,disabledFeatures
,meetingExpireIfNoUserJoinedInMinutes
,meetingExpireWhenLastUserLeftInMinutes
,preUploadedPresentationOverrideDefault
; Deprecated:learningDashboardEnabled
,breakoutRoomsEnabled
,virtualBackgroundsDisabled
. -
insertDocument endpoint was first introduced
Updated in 2.6:
-
create - Added:
notifyRecordingIsOn
,presentationUploadExternalUrl
,presentationUploadExternalDescription
,recordFullDurationMedia
(v2.6.9);disabledFeaturesExclude
(2.6.9); AddedliveTranscription
andpresentation
as options fordisabledFeatures
. -
getRecordings - Added: Added support for pagination using
offset
,limit
-
join: Added
userdata-bbb_hide_presentation_on_join
.
Updated in 2.7:
- create - Added:
preUploadedPresentation
,preUploadedPresentationName
,allowPromoteGuestToModerator
(2.7.9),disabledFeatures
optionscameraAsContent
,snapshotOfCurrentSlide
,downloadPresentationOriginalFile
,downloadPresentationConvertedToPdf
,timer
,learningDashboardDownloadSessionData
(2.7.5). - join - Added:
errorRedirectUrl
,userdata-bbb_fullaudio_bridge
Updated in 3.0:
- create - Added parameters:
allowOverrideClientSettingsOnCreateCall
,loginURL
. ParametermeetingLayout
supports a few new options: CAMERAS_ONLY, PARTICIPANTS_CHAT_ONLY, PRESENTATION_ONLY; Added POST module:clientSettingsOverride
; Added:disabledFeatures
optionsinfiniteWhiteboard
; - join - Added:
enforceLayout
,userdata-bbb_default_layout
,userdata-bbb_skip_echotest_if_previous_device
,userdata-bbb_prefer_dark_theme
. Removed:defaultLayout
(replaced byuserdata-bbb_default_layout
) and removed support for all HTTP request methods except GET. - sendChatMessage endpoint was first introduced.
- enter endpoint was removed. It was only used internally, never part of the api documentation.
- html5client/check endpoint was removed. It was used for checking the health of the server returning
{"html5clientStatus":"running"}
- feedback endpoint was introduced, replacing calls to
/html5client/feedback
with/api/feedback
API Data Types
There are three types in the API.
String:
This data type indicates a (UTF-8) encoded string. When passing String values to BigBlueButton API calls, make sure that you use correctly URL-encoded UTF-8 values so international text will show up correctly. The string must not contain control characters (values 0x00 through 0x1F).
Some BigBlueButton API parameters put additional restrictions on which characters are allowed, or on the lengths of the string. These restrictions are described in the parameter documentation.
Number:
This data type indicates a non-negative integer value. The parameter value must only contain the digits 0
through 9
. There should be no leading sign (+
or -
), and no comma or period characters.
Boolean:
A true/false value. The value must be specified as the literal string true
or false
(all lowercase), other values may be misinterpreted.
API Security Model
The BigBlueButton API security model enables 3rd-party applications to make API calls (if they have the shared secret), but not allow other people (end users) to make API calls.
The BigBlueButton API calls are almost all made server-to-server. If you installed the package bbb-demo
on your BigBlueButton server, you get a set of API examples, written in Java Server Pages (JSP), that demonstrate how to use the BigBlueButton API. These demos run as a web application in tomcat7. The web application makes HTTPS requests to the BigBlueButton server's API end point.
You can retrieve your BigBlueButton API parameters (API endpoint and shared secret) using the command
$ bbb-conf --secret
Here's a sample return
URL: http://bbb.example.com/bigbluebutton/
Secret: ECCJZNJWLPEA3YB6Y2LTQGQD3GJZ3F93
You should not embed the shared secret within a web page and make BigBlueButton API calls within JavaScript running within a browser. The built-in debugging tools for modern browser would make this secret easily accessible to any user. Once someone has the shared secret for your BigBlueButton server, they could create their own API calls. The shared secret should only be accessible to the server-side components of your application (and thus not visible to end users).
Configuration
The shared secret is located in the /etc/bigbluebutton/bbb-web.properties
file.
Look for the parameter securitySalt
(it's called securitySalt
due to legacy naming of the string)
securitySalt=<your_salt>
We'll refer to this value as sharedSecret
. When you first install BigBlueButton on a server, the packaging scripts create a random 32 character sharedSecret
. You can also change the sharedSecret
at anytime using the command bbb-conf --setsecret
.
$ sudo bbb-conf --setsecret <new_shared_secret>
The following command will create a new 32 character shared secret for your server
$ sudo bbb-conf --setsecret \$(openssl rand -base64 32 | sed 's/=//g' | sed 's/+//g' | sed 's/\///g')
IMPORTANT: DO NOT ALLOW END USERS TO KNOW YOUR SHARED SECRET OR ELSE YOUR SECURITY WILL BE COMPROMISED.
There are other configuration values in bbb-web's configuration bigbluebutton.properties
(overwritten by /etc/bigbluebutton/bbb-web.properties
) related to the lifecycle of a meeting. You don't need to understand all of these to start using the BigBlueButton API. For most BigBlueButton servers, you can leave the default values.
In BigBlueButton 2.5 support for additional hashing algorithms, besides sha1 and sha256, were added. These include sha384 and sha512. The supportedChecksumAlgorithms
property in bbb-web defines which algorithms are supported. By default checksums can be validated with any of the supported algorithms. To remove support for one or more of these algorithms simply delete it from the configuration file.
If you drop support for sha256, (for example if you want to force only sha512 to be used) you will also need to update the checkSumAlgorithmForBreakouts
property in akka-apps.
In /etc/bigbluebutton/bbb-web.properties
:
supportedChecksumAlgorithms=sha512
In /etc/bigbluebutton/bbb-apps-akka.conf
:
services {
checkSumAlgorithmForBreakouts = "sha512"
#...
}
And make sure to restart BigBlueButton.
Usage
The implementation of BigBlueButton's security model lies in the controller ApiController.groovy
. For each incoming API request, the controller computes a checksum out of the combination of the entire HTTPS query string and the server's shared secret. It then matches the incoming checksum against the computed checksum. If they match, the controller accepts the incoming request.
To use the security model, you must be able to create a SHA-1 checksum out of the call name plus the query string plus the shared secret that you configured on your server. To do so, follow these steps:
- Create the entire query string for your API call without the checksum parameter.
- Example for create meeting API call:
name=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444
- Example for create meeting API call:
- Prepend the API call name to your string
- Example for above query string:
- API call name is
create
- String becomes:
createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444
- API call name is
- Example for above query string:
- Now, append the shared secret to your string
- Example for above query string:
- shared secret is
639259d4-9dd8-4b25-bf01-95f9567eaf4b
- String becomes:
createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444639259d4-9dd8-4b25-bf01-95f9567eaf4b
- shared secret is
- Example for above query string:
- Now, find the SHA-1 sum for that string (implementation varies based on programming language).
- the SHA-1 sum for the above string is:
1fcbb0c4fc1f039f73aa6d697d2db9ba7f803f17
- the SHA-1 sum for the above string is:
- Add a checksum parameter to your query string that contains this checksum.
- Above example becomes:
name=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444&checksum=1fcbb0c4fc1f039f73aa6d697d2db9ba7f803f17
- Above example becomes:
You MUST send this checksum with EVERY API call. Since end users do not know your shared secret, they can not fake calls to the server, and they can not modify any API calls since changing a single parameter name or value by only one character will completely change the checksum required to validate the call.
NOTE Checksums for POST requests must be calculated using the URL query string as well. For example, if all request parameters are in the request body then the checksum will be calculated using an empty query string.
Implementations of the SHA-1 functionality exist in nearly all programming languages. Here are example methods or links to example implementations for various languages:
- JavaScript
- describes MD5 also
- Java
- You can use
org.apache.commons.codec.digest.DigestUtils
and callDigestUtils.shaHex(string + sharedSecret)
- You can use
- PHP
- simply call
sha1(string . sharedSecret)
- simply call
Error handling
In the case of an error, all API calls make a best-effort attempt to return a properly formatted XML that contains enough information for the caller to determine the source of the error.
Errors are returned with a returncode
value of FAILED
and a message
and messageKey
value. We will try very hard to keep the messageKey stable (unchanging) throughout the life of the API. However, the message
value is a plain text (English) value that may change with time.
You can use the messageKey
to determine the type of error and look up internationalized text within your own system if needed. For example, an invalid request may return an error message of "No conference with that meeting ID exists", but the messageKey is simple "invalidMeetingIdentifier".
API Resources
Administration
The following section describes the administration calls
Resource | Description |
---|---|
create | Creates a new meeting. |
join | Join a new user to an existing meeting. |
end | Ends meeting. |
sendChatMessage | Send a message to the public chat. |
insertDocument | Insert a batch of documents via API call |
Monitoring
The following section describes the monitoring calls
Resource | Description |
---|---|
isMeetingRunning | Checks whether if a specified meeting is running. |
getMeetings | Get the list of Meetings. |
getMeetingInfo | Get the details of a Meeting. |
Recording
Resource | Description |
---|---|
getRecordings | Get a list of recordings. |
publishRecordings | Enables publishing or unpublishing of a recording. |
deleteRecordings | Deletes an existing recording |
updateRecordings | Updates metadata in a recording. |
getRecordingTextTracks | Get a list of the caption/subtitle. |
putRecordingTextTrack | Upload a caption or subtitle file to add it to the recording. |
API Calls
The following response parameters are standard to every call and may be returned from any call.
Parameters:
Param Name | Required / Optional | Type | Description |
---|---|---|---|
checksum | Varies | String | See the API Security ModelAnchor section for more details on the usage for this parameter. This is basically a SHA-1 hash of callName + queryString + sharedSecret . The security salt will be configured into the application at deploy time. All calls to the API must include the checksum parameter. |
Response:
Param Name | When Returned | Type | Description |
---|---|---|---|
returncode | Always | String | Indicates whether the intended function was successful or not. Always one of two values:FAILED – There was an error of some sort – look for the message and messageKey for more information. Note that if the returncode is FAILED, the call-specific response parameters marked as “always returned” will not be returned. They are only returned as part of successful responses.SUCCESS – The call succeeded – the other parameters that are normally associated with this call will be returned. |
message | Sometimes | String | A message that gives additional information about the status of the call. A message parameter will always be returned if the returncode was FAILED . A message may also be returned in some cases where returncode was SUCCESS if additional information would be helpful. |
messageKey | Sometimes | String | Provides similar functionality to the message and follows the same rules. However, a message key will be much shorter and will generally remain the same for the life of the API whereas a message may change over time. If your third party application would like to internationalize or otherwise change the standard messages returned, you can look up your own custom messages based on this messageKey. |
GET
POST
create
Creates a BigBlueButton meeting.
The create call is idempotent: you can call it multiple times with the same parameters without side effects. This simplifies the logic for joining a user into a session as your application can always call create before returning the join URL to the user. This way, regardless of the order in which users join, the meeting will always exist when the user tries to join (the first create
call actually creates the meeting; subsequent calls to create
simply return SUCCESS
).
The BigBlueButton server will automatically remove empty meetings that were created but have never had any users after a number of minutes specified by meetingExpireIfNoUserJoinedInMinutes
defined in bbb-web's properties.
Resource URL:
http://yourserver.com/bigbluebutton/api/create?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
name (required) | String | A name for the meeting. This is now required as of BigBlueButton 2.4. |
meetingID (required) | String | A meeting ID that can be used to identify this meeting by the 3rd-party application. This must be unique to the server that you are calling: different active meetings can not have the same meeting ID. If you supply a non-unique meeting ID (a meeting is already in progress with the same meeting ID), then if the other parameters in the create call are identical, the create call will succeed (but will receive a warning message in the response). The create call is idempotent: calling multiple times does not have any side effect. This enables a 3rd-party applications to avoid checking if the meeting is running and always call create before joining each user. Meeting IDs should only contain upper/lower ASCII letters, numbers, dashes, or underscores. A good choice for the meeting ID is to generate a GUID value as this all but guarantees that different meetings will not have the same meetingID. |
attendeePW | String | [DEPRECATED] The password that the join URL can later provide as its password parameter to indicate the user will join as a viewer. If no attendeePW is provided, the create call will return a randomly generated attendeePW password for the meeting. |
moderatorPW | String | [DEPRECATED] The password that will join URL can later provide as its password parameter to indicate the user will as a moderator. if no moderatorPW is provided, create will return a randomly generated moderatorPW password for the meeting. |
welcome | String | A welcome message that gets displayed on the chat window when the participant joins. You can include keywords (%%CONFNAME%% , %%DIALNUM%% , %%CONFNUM%% ) which will be substituted automatically.This parameter overrides the default defaultWelcomeMessage in bigbluebutton.properties .The welcome message has limited support for HTML formatting. Be careful about copy/pasted HTML from e.g. MS Word, as it can easily exceed the maximum supported URL length when used on a GET request. |
dialNumber | String | The dial access number that participants can call in using regular phone. You can set a default dial number via defaultDialAccessNumber in bigbluebutton.properties |
voiceBridge | String | Voice conference number for the FreeSWITCH voice conference associated with this meeting. This must be a 5-digit number in the range 10000 to 99999. If you add a phone number to your BigBlueButton server, This parameter sets the personal identification number (PIN) that FreeSWITCH will prompt for a phone-only user to enter. If you want to change this range, edit FreeSWITCH dialplan and defaultNumDigitsForTelVoice of bigbluebutton.properties.The voiceBridge number must be different for every meeting.This parameter is optional. If you do not specify a voiceBridge number, then BigBlueButton will assign a random unused number for the meeting.If do you pass a voiceBridge number, then you must ensure that each meeting has a unique voiceBridge number; otherwise, reusing same voiceBridge number for two different meetings will cause users from one meeting to appear as phone users in the other, which will be very confusing to users in both meetings. |
maxParticipants | Number | Set the maximum number of users allowed to joined the conference at the same time. |
loginURL | String | Enables third-party applications to provide a URL that users can access during a meeting to join the session directly. |
logoutURL | String | The URL that the BigBlueButton client will go to after users click the OK button on the ‘You have been logged out message’. This overrides the value for bigbluebutton.web.logoutURL in bigbluebutton.properties. |
record | Boolean | Setting ‘record=true’ instructs the BigBlueButton server to record the media and events in the session for later playback. The default is false. In order for a playback file to be generated, a moderator must click the Start/Stop Recording button at least once during the session; otherwise, in the absence of any recording marks, the record and playback scripts will not generate a playback file. See also the autoStartRecording and allowStartStopRecording parameters in bigbluebutton.properties. |
duration | Number | The maximum length (in minutes) for the meeting. Normally, the BigBlueButton server will end the meeting when either (a) the last person leaves (it takes a minute or two for the server to clear the meeting from memory) or when the server receives an end API request with the associated meetingID (everyone is kicked and the meeting is immediately cleared from memory). BigBlueButton begins tracking the length of a meeting when it is created. If duration contains a non-zero value, then when the length of the meeting exceeds the duration value the server will immediately end the meeting (equivalent to receiving an end API request at that moment). |
isBreakout | Boolean | Must be set to true to create a breakout room. |
parentMeetingID | String | Must be provided when creating a breakout room, the parent room must be running. |
sequence | Number | The sequence number of the breakout room. |
freeJoin | Boolean | If set to true, the client will give the user the choice to choose the breakout rooms he wants to join. |
breakoutRoomsEnabled | Boolean | [DEPRECATED] Removed in 2.5, temporarily still handled, please transition to disabledFeatures. If set to false, breakout rooms will be disabled. Default: |
breakoutRoomsPrivateChatEnabled | Boolean | If set to false, the private chat will be disabled in breakout rooms. Default: |
breakoutRoomsRecord | Boolean | If set to false, breakout rooms will not be recorded. Default: |
meta | String | This is a special parameter type (there is no parameter named just meta ).You can pass one or more metadata values when creating a meeting. These will be stored by BigBlueButton can be retrieved later via the getMeetingInfo and getRecordings calls. Examples of the use of the meta parameters are meta_Presenter=Jane%20Doe , meta_category=FINANCE , and meta_TERM=Fall2016 . |
moderatorOnlyMessage | String | Display a message to all moderators in the public chat. The value is interpreted in the same way as the welcome parameter. |
autoStartRecording | Boolean | Whether to automatically start recording when first user joins (default false ).When this parameter is true , the recording UI in BigBlueButton will be initially active. Moderators in the session can still pause and restart recording using the UI control.<br/NOTE: Don’t pass autoStartRecording=false and allowStartStopRecording=false - the moderator won’t be able to start recording! |
allowStartStopRecording | Boolean | Allow the user to start/stop recording. (default true) If you set both allowStartStopRecording=false and autoStartRecording=true , then the entire length of the session will be recorded, and the moderators in the session will not be able to pause/resume the recording. |
webcamsOnlyForModerator | Boolean | Setting webcamsOnlyForModerator=true will cause all webcams shared by viewers during this meeting to only appear for moderators (added 1.1) |
bannerText | String | Will set the banner text in the client. (added 2.0) |
bannerColor | String | Will set the banner background color in the client. The required format is color hex #FFFFFF. (added 2.0) |
muteOnStart | Boolean | Setting true will mute all users when the meeting starts. (added 2.0) |
allowModsToUnmuteUsers | Boolean | Setting to true will allow moderators to unmute other users in the meeting. (added 2.2)Default: |
lockSettingsDisableCam | Boolean | Setting true will prevent users from sharing their camera in the meeting. (added 2.2)Default: |
lockSettingsDisableMic | Boolean | Setting to true will only allow user to join listen only. (added 2.2)Default: |
lockSettingsDisablePrivateChat | Boolean | Setting to true will disable private chats in the meeting. (added 2.2)Default: |
lockSettingsDisablePublicChat | Boolean | Setting to true will disable public chat in the meeting. (added 2.2)Default: |
lockSettingsDisableNotes | Boolean | Setting to true will disable notes in the meeting. (added 2.2)Default: |
lockSettingsHideUserList | Boolean | Setting to true will prevent viewers from seeing other viewers in the user list. (added 2.2)Default: |
lockSettingsLockOnJoin | Boolean | Setting to false will not apply lock setting to users when they join. (added 2.2)Default: |
lockSettingsLockOnJoinConfigurable | Boolean | Setting to true will allow applying of lockSettingsLockOnJoin .Default: |
lockSettingsHideViewersCursor | Boolean | Setting to true will prevent viewers to see other viewers cursor when multi-user whiteboard is on. (added 2.5)Default: |
guestPolicy | Enum | Will set the guest policy for the meeting. The guest policy determines whether or not users who send a join request with guest=true will be allowed to join the meeting. Possible values are ALWAYS_ACCEPT, ALWAYS_DENY, and ASK_MODERATOR.Default: |
keepEvents | Boolean | Removed in 2.3 in favor of meetingKeepEvents and bigbluebutton.properties defaultKeepEvents . |
meetingKeepEvents | Boolean | Defaults to the value of defaultKeepEvents . If meetingKeepEvents is true BigBlueButton saves meeting events even if the meeting is not recorded (added in 2.3)Default: |
endWhenNoModerator | Boolean | Default endWhenNoModerator=false . If endWhenNoModerator is true the meeting will end automatically after a delay - see endWhenNoModeratorDelayInMinutes (added in 2.3)Default: |
endWhenNoModeratorDelayInMinutes | Number | Defaults to the value of endWhenNoModeratorDelayInMinutes=1 . If endWhenNoModerator is true, the meeting will be automatically ended after this many minutes (added in 2.2)Default: |
meetingLayout | Enum | Will set the default layout for the meeting. Possible values are: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS. (added 2.4) In version 3.0 a few more possible options were added: CAMERAS_ONLY, PRESENTATION_ONLY, PARTICIPANTS_AND_CHAT_ONLY Default: |
learningDashboardEnabled | Boolean | [DEPRECATED] Removed in 2.5, temporarily still handled, please transition to disabledFeatures. Default learningDashboardEnabled=true . When this option is enabled BigBlueButton generates a Dashboard where moderators can view a summary of the activities of the meeting. (added 2.4)Default: |
learningDashboardCleanupDelayInMinutes | Number | Default learningDashboardCleanupDelayInMinutes=2 . This option set the delay (in minutes) before the Learning Dashboard become unavailable after the end of the meeting. If this value is zero, the Learning Dashboard will keep available permanently. (added 2.4)Default: |
allowModsToEjectCameras | Boolean | Setting to true will allow moderators to close other users cameras in the meeting. (added 2.4)Default: |
allowRequestsWithoutSession | Boolean | Setting to true will allow users to join meetings without session cookie's validation. (added 2.4.3)Default: |
virtualBackgroundsDisabled | Boolean | [DEPRECATED] Removed in 2.5, temporarily still handled, please transition to disabledFeatures. Setting to true will disable Virtual Backgrounds for all users in the meeting. (added 2.4.3)Default: |
userCameraCap | Number | Setting to 0 will disable this threshold. Defines the max number of webcams a single user can share simultaneously. (added 2.4.5)Default: |
meetingCameraCap | Number | Setting to 0 will disable this threshold. Defines the max number of webcams a meeting can have simultaneously. (added 2.5.0)Default: |
meetingExpireIfNoUserJoinedInMinutes | Number | Automatically end meeting if no user joined within a period of time after meeting created. (added 2.5) Default: |
meetingExpireWhenLastUserLeftInMinutes | Number | Number of minutes to automatically end meeting after last user left. (added 2.5) Setting to 0 will disable this function.Default: |
groups | String | Pre-defined groups to automatically assign the students to a given breakout room. (added 2.5) Expected value: Json with Array of groups. Group properties:
E.g: [ |
logo | String | Pass a URL to an image which will then be visible in the area above the participants list if displayBrandingArea is set to true in bbb-html5's configuration |
disabledFeatures | String | List (comma-separated) of features to disable in a particular meeting. (added 2.5) Available options to disable:
|
disabledFeaturesExclude | String | List (comma-separated) of features to no longer disable in a particular meeting. This is particularly useful if you disabled a list of features on a per-server basis but want to allow one of two of these features for a specific meeting. (added 2.6.9) The available options to exclude are exactly the same as for disabledFeatures |
preUploadedPresentationOverrideDefault | Boolean | If it is true, the default.pdf document is not sent along with the other presentations in the /create endpoint, on the other hand, if that's false, the default.pdf is sent with the other documents. By default it is true.Default: |
notifyRecordingIsOn | Boolean | If it is true, a modal will be displayed to collect recording consent from users when meeting recording starts (only if notifyRecordingIsOn=true ). By default it is false. (added 2.6)Default: |
presentationUploadExternalUrl | String | Pass a URL to a specific page in external application to select files for inserting documents into a live presentation. Only works if presentationUploadExternalDescription is also set. (added 2.6) |
presentationUploadExternalDescription | String | Message to be displayed in presentation uploader modal describing how to use an external application to upload presentation files. Only works if presentationUploadExternalUrl is also set. (added 2.6) |
recordFullDurationMedia | Boolean | Controls whether media (audio, cameras and screen sharing) should be captured on their full duration if the meeting's recorded property is true (recorded=true ). Default is false: only captures media while recording is running in the meeting. (added 2.6.9)Default: |
preUploadedPresentation | String | If passed with a valid presentation file url, this presentation will override the default presentation. To only upload but not set as default, also pass preUploadedPresentationOverrideDefault=false (added 2.7.2) |
preUploadedPresentationName | String | If passed it will use this string as the name of the presentation uploaded via preUploadedPresentation (added 2.7.2) |
allowOverrideClientSettingsOnCreateCall | String | (added in BBB 3.0.0-alpha.1) Default: |
clientSettingsOverride | String | The included structure will override settings.yml needed for the HTML5 client. For an example for the HTTPS POST request check clientSettingsOverride section in API(added in BBB 3.0.0-alpha.5) |
allowPromoteGuestToModerator | Boolean | If passed as true, we allow moderators to promote guests to moderators even if the authenticatedGuest config is enabled. The defaultAllowPromoteGuestToModerator configuration sets this behaviour globally for all meetings if no api parameter is passed (added in BBB 2.7.9) Default: |
Example Requests:
- http://yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&checksum=1234
- http://yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&moderatorPW=mp&attendeePW=ap&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&moderatorPW=mp&attendeePW=ap&meta_presenter=joe&meta_category=education&checksum=abcd
Example Response:
<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>
POST request
You can also include a payload in the request, it may be useful in cases where some of the query parameters are big enough to exceed the maximum number of characters in URLs. BigBlueButton supports a POST request where the parameters that usually would be passed in the URL, can be sent through the body, see example below:
curl --request POST \
--url https://<your-host>/bigbluebutton/api/create \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data welcome=Welcome \
--data allowStartStopRecording=true \
--data attendeePW=ap \
--data autoStartRecording=false \
--data meetingID=random-1730297 \
--data moderatorPW=mp \
--data name=random-1730297 \
--data record=false \
--data `voiceBridge`=71296 \
--data checksum=1234;
It will be further explored in the next section the possibility of sending other data types in the payload as well.
One other think to pay attention is to not include any of the parameters in both the URL and the body, or else it will pop a checksum does not match
error:
<response>
<returncode>FAILED</returncode>
<messageKey>checksumError</messageKey>
<message>Checksums do not match</message>
</response>
Pre-upload Slides
You can upload slides within the create call. If you do this, the BigBlueButton server will immediately download and process the slides.
You can pass the slides as a URL or embed the slides in base64 as part of the POST request. For embedding the slides, you have to send a HTTPS POST request (by default, the total size of the POST request can't exceed 2MB, so embedding very large slides won't work). The URL Resource has to be the same as the previously described.
In the body part, you would append a simple XML like the example below:
<modules>
<module name="presentation">
<document url="http://www.sample-pdf.com/sample.pdf" filename="report.pdf"/>
<document name="sample-presentation.pdf">JVBERi0xLjQKJ....
[clipped here]
....0CiUlRU9GCg==
</document>
</module>
</modules>
When you need to provide a document using a URL, and the document URL does not contain an extension, you can use the filename
parameter, such as filename=test-results.pdf
to help the BigBlueButton server determine the file type (in this example it would be a PDF file).
From 2.5.x
and on there is also 2 parameters one can provide the payload to ensure that the document they are uploading can be downloaded or removed from the meeting, those parameters are:
Parameter | Description | Default Value |
---|---|---|
downloadable | Dictates if the presentation can be downloaded | true |
removable | dictates if one can remove the presentation. | false |
In the payload the variables are passed inside each <document>
tag of the xml, as follows:
<document downloadable="false" removable="true" url="http://www.sample-pdf.com/sample.pdf" filename="report.pdf"/>
<document removable="false" name="sample-presentation.pdf">JVBERi0xLjQKJ....
[clipped here]
....0CiUlRU9GCg==
</document>
In the case more than a single document is provided, the first one will be loaded in the client, the processing of the other documents will continue in the background and they will be available for display when the user select one of them from the client.
For more information about the pre-upload slides check the following link.
clientSettingsOverride
You can modify the settings.yml
configuration for the HTML5 client as part of the create call (in addition to modifying /etc/bigbluebutton/bbb-html5.yml
).
You can construct the HTTPS POST request as follows:
curl -s -X POST "$URL/$CONTROLLER?$PARAMS&checksum=$CHECKSUM" --header "Content-Type: application/xml" --data '
<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>'
Upload slides from external application to a live BigBlueButton session
For external applications that integrate to BigBlueButton using the insertDocument API call, presentationUploadExternalUrl
and presentationUploadExternalDescription
parameters can be used in the create
API call in order to display a button and a message in the bottom of the presentation upload dialog.
Clicking this button will open the URL in a new tab that shows the file picker for the external application. The user can then select files in the external application and they will be sent to the live session.
End meeting callback URL
You can ask the BigBlueButton server to make a callback to your application when the meeting ends. Upon receiving the callback your application could, for example, change the interface for the user to hide the 'join' button.
To specify the callback to BigBlueButton, pass a URL using the meta-parameter meta_endCallbackUrl
on the create
command. When the BigBlueButton server ends the meeting, it will check if meta_endCallbackUrl
is sent URL and, if so, make a HTTP GET request to the given URL.
For example, to specify the callback URL as
https://myapp.example.com/callback?meetingID=test01
add the following parameter to the create
API call: &meta_endCallbackUrl=https%3A%2F%2Fmyapp.example.com%2Fcallback%3FmeetingID%3Dtest01
(note the callback URL needs to be URLEncoded).
Later, when the meeting ends, BigBlueButton will make an HTTPS GET request to this URL (HTTPS is supported and recommended) and to the URL add an additional parameter: recordingmarks=true|false
.
The value for recordingmarks
will be true
if (a) the meeting was set to be recorded (record=true
was passed on the create API call), and (b) a moderator clicked the Start/Stop Record button during the meeting (which places recording marks in the events). Given the example URL above, here's the final callback if both (a) and (b) are true:
https://myapp.example.com/callback?meetingID=test01&recordingmarks=true
Another param is the meetingEndedURL
create param. This create param is a callback to indicate the meeting has ended. This is a duplicate of the endCallbackUrl meta param. We have this separate as we want this param to stay on the server and not propagated to client and recordings. Can be used by scalelite to be notified right away when meeting ends. The meta callback url can be used to inform third parties.
Recording ready callback URL
You can ask the BigBlueButton server to make a callback to your application when the recording for a meeting is ready for viewing. Upon receiving the callback your application could, for example, send the presenter an e-mail to notify them that their recording is ready.
To specify the callback to BigBlueButton, pass a URL using the meta-parameter meta_bbb-recording-ready-url
on the create
command. Later, when the BigBlueButton server finishes processing the recording, it will check if meta_bbb-recording-ready-url
is set and, if so, make a HTTP POST request to the given URL.
For example, given the callback URL
https://example.com/api/v1/recording_status
to pass this to BigBlueButton add the following parameter to the create
API call: &meta_bbb-recording-ready-url=https%3A%2F%2Fexample.com%2Fapi%2Fv1%2Frecording_status
(note the callback URL needs to be URLEncoded).
Later, when the recording is ready, the BigBlueButton server will make an HTTPS POST request to this URL (https is supported and recommended).
The POST request body will be in the standard application/x-www-form-urlencoded
format. The body will contain one parameter, named signed_parameters
. The value of this parameter is a JWT (JSON Web Tokens) encoded string.
The JWT will be encoded using the "HS256" method. (i.e. the header should be { "typ": "JWT", "alg": "HS256" }
). The payload will contain a the following JSON keys:
meeting_id
- The value will be the meeting_id (as provided on the BigBlueButton create API call).record_id
- The identifier of the specific recording to which the notification applies. This corresponds to the IDs returned in the getRecordings api, and theinternalMeetingId
field on the getMeetingInfo request.
The secret used to sign the JWT message will be the shared secret of the BigBlueButton API endpoint that was used to create the original meeting.
The receiving endpoint should respond with one of the following HTTP codes to indicate status, as described below. Any response body provided will be ignored, although it may be logged as part of error handling.
Response Code | Description |
---|---|
2XX | All HTTP 2XX codes are treated the same way - the endpoint has received the notification, and the recording system will consider the callback completed. I suggest using the 200, 202, or 204 codes as appropriate to your application. |
3XX | Redirections are not supported, and will be treated as an error. |
401 | The shared secret does not match. |
410 | The callback is for a meeting/session/recording that has been deleted in the application. This code may in the future trigger the recording system to cancel the recording processing or unpublish and delete the recording. |
All other HTTP response codes will be treated as transient errors.
GET
join
Joins a user to the meeting specified in the meetingID parameter.
Resource URL:
http://yourserver.com/bigbluebutton/api/join?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
fullName (required) | String | The full name that is to be used to identify this user to other conference attendees. |
meetingID (required) | String | The meeting ID that identifies the meeting you are attempting to join. |
password (required) | String | [DEPRECATED] This password value is used to determine the role of the user based on whether it matches the moderator or attendee password. Note: This parameter is not required when the role parameter is passed. |
role (required) | String | Define user role for the meeting. Valid values are MODERATOR or VIEWER (case insensitive). If the role parameter is present and valid, it overrides the password parameter. You must specify either password parameter or role parameter in the join request. |
createTime | String | Third-party apps using the API can now pass createTime parameter (which was created in the create call), BigBlueButton will ensure it matches the ‘createTime’ for the session. If they differ, BigBlueButton will not proceed with the join request. This prevents a user from reusing their join URL for a subsequent session with the same meetingID. |
userID | String | An identifier for this user that will help your application to identify which person this is. This user ID will be returned for this user in the getMeetingInfo API call so that you can check |
webVoiceConf | String | If you want to pass in a custom voice-extension when a user joins the voice conference using voip. This is useful if you want to collect more info in you Call Detail Records about the user joining the conference. You need to modify your /etc/asterisk/bbb-extensions.conf to handle this new extensions. |
avatarURL | String | The link for the user’s avatar to be displayed (default can be enabled/disabled and set with “useDefaultAvatar“ and “defaultAvatarURL“ in bbb-web.properties). |
webcamBackgroundURL | String | The link for the user's webcam background to be displayed (default can be enabled/disabled and set with “useDefaultWebcamBackground“ and “defaultWebcamBackgroundURL“ in bigbluebutton.properties). Added in BigBlueButton 2.7.10. |
redirect | String | The default behaviour of the JOIN API is to redirect the browser to the HTML5 client when the JOIN call succeeds. There have been requests if it’s possible to embed the HTML5 client in a “container” page and that the client starts as a hidden DIV tag which becomes visible on the successful JOIN. Setting this variable to FALSE will not redirect the browser but returns an XML instead whether the JOIN call has succeeded or not. The third party app is responsible for displaying the client to the user. |
errorRedirectUrl | String | A custom URL to redirect users to when an error occurs while joining. By default users are redirected to the meeting's default logout URL. |
joinViaHtml5 | String | [DEPRECATED]Set to “true” to force the HTML5 client to load for the user. (removed in 2.3 since HTML5 is the only client) |
guest | String | Set to “true” to indicate that the user is a guest, otherwise do NOT send this parameter. |
bot | String | Set to “true” to indicate that the user is a bot or an automated agent, otherwise do NOT send this parameter. |
excludeFromDashboard | String | If the parameter is passed on JOIN with value `true`, the user will be omitted from being displayed in the Learning Dashboard. The use case is for support agents who drop by to support the meeting / resolve tech difficulties. Added in BBB 2.4 |
enforceLayout | String | If passed it overrides the value of `meetingLayout` passed on CREATE or the value of `defaultMeetingLayout` read from configuration. Accepted values are the standard layouts: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, but also several layouts which are not meant to be selectable via UI: CAMERAS_ONLY, PARTICIPANTS_CHAT_ONLY, PRESENTATION_ONLY. Added in BBB 3.0 |
Example Requests:
- http://yourserver.com/bigbluebutton/api/join?meetingID=test01&password=mp&fullName=John&checksum=1234
- http://yourserver.com/bigbluebutton/api/join?meetingID=test01&password=ap&fullName=Mark&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/join?meetingID=test01&password=ap&fullName=Chris&createTime=273648&checksum=abcd
Example Response:
There is a XML response for this call only when the redirect
parameter is set to false
. You should simply redirect the user to the call URL, and they will be entered into the meeting.
<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>
See Passing user metadata to the client on join for additional join
parameters that can override default settings for the user.
POST
insertDocument
This endpoint insert one or more documents into a running meeting via API call.
Resource URL:
https://yourserver.com/bigbluebutton/api/insertDocument?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID (required) | String | The meeting ID that identifies the meeting you want to insert documents. |
Example Requests:
You can do the request either via greenlight or curl
, which I am going to demonstrate in the following paragraph.
First, it is necessary to have the xml string with the batch of the wanted presentations in hand. As an example, see the xml down below:
<modules>
<module name="presentation">
<document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
<document removable="false" name="sample.pdf">
JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
</document>
</module>
</modules>
Now you need to write the curl
command which will be:
curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '{xml}'
Combining both together, we get:
curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '<modules>
<module name="presentation">
<document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
<document removable="false" name="sample.pdf">
JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
</document>
</module>
</modules>'
There is also the possibility of passing the removable and downloadable variables inside the payload, they go in the document
tag as already demonstrated. The way it works is exactly the same as in the (POST) create endpoint
GET
POST
isMeetingRunning
This call enables you to simply check on whether or not a meeting is running by looking it up with your meeting ID.
Resource URL:
http://yourserver.com/bigbluebutton/api/isMeetingRunning?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID (required) | String | The meeting ID that identifies the meeting you are attempting to check on. |
Example Requests:
http://yourserver.com/bigbluebutton/api/isMeetingRunning?meetingID=test01&checksum=1234
Example Response:
<response>
<returncode>SUCCESS</returncode>
<running>true</running>
</response>
running can be “true” or “false” that signals whether a meeting with this ID is currently running.
GET
POST
end
Use this to forcibly end a meeting and kick all participants out of the meeting.
Resource URL:
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID (required) | String | The meeting ID that identifies the meeting you are attempting to end. |
password (required) | String | [DEPRECATED] The moderator password for this meeting. You can not end a meeting using the attendee password. |
Example Requests:
Example Response:
<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>
POST request
Just like the create request, you can send a POST to end the meeting, the syntax is pretty much the same, see example below:
curl --request POST \
--url https://<your-host>/bigbluebutton/api/end \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data meetingID=Test+Meeting \
--data password=mp \
--data checksum=1234
IMPORTANT NOTE: You should note that when you call end meeting, it is simply sending a request to the backend (Red5) server that is handling all the conference traffic. That backend server will immediately attempt to send every connected client a logout event, kicking them from the meeting. It will then disconnect them, and the meeting will be ended. However, this may take several seconds, depending on network conditions. Therefore, the end meeting call will return a success as soon as the request is sent. But to be sure that it completed, you should then check back a few seconds later by using the getMeetingInfo
or isMeetingRunning
calls to verify that all participants have left the meeting and that it successfully ended.
GET
POST
getMeetingInfo
This call will return all of a meeting's information, including the list of attendees as well as start and end times.
Resource URL:
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID (required) | String | The meeting ID that identifies the meeting you are attempting to check on. |
Example Requests:
Example Response:
<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>
<attendeePW>1umEM3ic</attendeePW>
<moderatorPW>V91JirCa</moderatorPW>
<running>true</running>
<duration>0</duration>
<hasUserJoined>true</hasUserJoined>
<recording>true</recording>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<startTime>1715261728142</startTime>
<endTime>0</endTime>
<participantCount>1</participantCount>
<listenerCount>0</listenerCount>
<voiceParticipantCount>1</voiceParticipantCount>
<videoCount>1</videoCount>
<maxUsers>0</maxUsers>
<moderatorCount>1</moderatorCount>
<attendees>
<attendee>
<userID>w_ftcrsyuh44oj</userID>
<fullName>Anton G</fullName>
<role>MODERATOR</role>
<isPresenter>true</isPresenter>
<isListeningOnly>false</isListeningOnly>
<hasJoinedVoice>true</hasJoinedVoice>
<hasVideo>true</hasVideo>
<clientType>HTML5</clientType>
<customdata></customdata>
</attendee>
</attendees>
<metadata>
<bbb-origin-version>summit2024-6d8120x</bbb-origin-version>
<bbb-origin-server-name>test30.bigbluebutton.org</bbb-origin-server-name>
<bbb-recording-ready-url>https://test30.bigbluebutton.org/recording_ready</bbb-recording-ready-url>
<bbb-origin>greenlight</bbb-origin>
<endcallbackurl>https://test30.bigbluebutton.org/meeting_ended</endcallbackurl>
</metadata>
<isBreakout>false</isBreakout>
</response>
If a meeting has spawned breakout rooms, then getMeetingInfo
will also a list of meetingIDs for the breakout rooms.
<response>
<returncode>success</returncode>
...
<breakoutRooms>
<breakout>breakout-room-id-1</breakout>
<breakout>breakout-room-id-2</breakout>
<breakout>breakout-room-id-3</breakout>
</breakoutRooms>
</response>
If a meeting is a breakout room itself, then getMeetingInfo
will also return a link to the parent meetingID.
<response>
<returncode>success</returncode>
...
<breakout>
<parentMeetingID>ParentMeetingId</parentMeetingID>
<sequence>1</sequence>
<freeJoin>false</freeJoin>
</breakout>
</response>
GET
POST
getMeetings
This call will return a list of all the meetings found on this server.
Resource URL:
http://yourserver.com/bigbluebutton/api/getMeetings?checksum=[checksum]
Parameters:
Since BigBlueButton 0.80, it is no more required to pass any parameter for this call.
Example Requests:
http://yourserver.com/bigbluebutton/api/getMeetings?checksum=1234
Example Response:
<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>
GET
getRecordings
Retrieves the recordings that are available for playback for a given meetingID (or set of meeting IDs). Support for pagination was added in 2.6.
Resource URL:
http://yourserver.com/bigbluebutton/api/getRecordings?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID | String | A meeting ID for get the recordings. It can be a set of meetingIDs separate by commas. If the meeting ID is not specified, it will get ALL the recordings. If a recordID is specified, the meetingID is ignored. |
recordID | String | A record ID for get the recordings. It can be a set of recordIDs separate by commas. If the record ID is not specified, it will use meeting ID as the main criteria. If neither the meeting ID is specified, it will get ALL the recordings. The recordID can also be used as a wildcard by including only the first characters in the string. |
state | String | Since version 1.0 the recording has an attribute that shows a state that Indicates if the recording is [processing|processed|published|unpublished|deleted]. The parameter state can be used to filter results. It can be a set of states separate by commas. If it is not specified only the states [published|unpublished] are considered (same as in previous versions). If it is specified as “any”, recordings in all states are included. |
meta | String | You can pass one or more metadata values to filter the recordings returned. The format of these parameters is the same as the metadata passed to the create call. For more information see the docs for the create call. |
offset | Integer | The starting index for returned recordings. Number must greater than or equal to 0. |
limit | Integer | The maximum number of recordings to be returned. Number must be between 1 and 100. |
Example Requests:
- http://yourserver.com/bigbluebutton/api/getRecordings?checksum=1234
- http://yourserver.com/bigbluebutton/api/getRecordings?meetingID=CS101&checksum=abcd
- http://yourserver.com/bigbluebutton/api/getRecordings?meetingID=CS101,CS102&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93-1462283509434&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93-1462283509434,9e359d17635e163c4388281567601d7fecf29df8-1461882579628&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93,9e359d17635e163c4388281567601d7fecf29df8&checksum=wxyz
- http://yourserver.com/bigbluebutton/api/getRecordings?state=published&offset=20&limit=10&checksum=abc123
Example Response:
Here the getRecordings
API call returned back two recordings for the meetingID c637ba21adcd0191f48f5c4bf23fab0f96ed5c18
. Each recording had two formats: podcast
and presentation
.
<response>
<returncode>SUCCESS</returncode>
<recordings>
<recording>
<recordID>ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</recordID>
<meetingID>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingID>
<internalMeetingID>ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</internalMeetingID>
<name>Fred's Room</name>
<isBreakout>false</isBreakout>
<published>true</published>
<state>published</state>
<startTime>1530718721124</startTime>
<endTime>1530718810456</endTime>
<participants>3</participants>
<metadata>
<isBreakout>false</isBreakout>
<meetingName>Fred's Room</meetingName>
<gl-listed>false</gl-listed>
<meetingId>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingId>
</metadata>
<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>
<preview>
<images>
<image alt="Welcome to" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-1.png</image>
<image alt="(this slide left blank for use as a whiteboard)" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-2.png</image>
<image alt="(this slide left blank for use as a whiteboard)" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-3.png</image>
</images>
</preview>
</format>
</playback>
</recording>
<recording>
<recordID>ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</recordID>
<meetingID>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingID>
<internalMeetingID>ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</internalMeetingID>
<name>Fred's Room</name>
<isBreakout>false</isBreakout>
<published>true</published>
<state>published</state>
<startTime>1530278898111</startTime>
<endTime>1530281194326</endTime>
<participants>7</participants>
<metadata>
<meetingName>Fred's Room</meetingName>
<isBreakout>false</isBreakout>
<gl-listed>true</gl-listed>
<meetingId>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingId>
</metadata>
<playback>
<format>
<type>podcast</type>
<url>https://demo.bigbluebutton.org/podcast/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/audio.ogg</url>
<processingTime>0</processingTime>
<length>33</length>
</format>
<format>
<type>presentation</type>
<url>https://demo.bigbluebutton.org/playback/presentation/2.0/playback.html?meetingId=ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</url>
<processingTime>139458</processingTime>
<length>33</length>
<preview>
<images>
<image width="176" height="136" alt="Welcome to">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-1.png</image>
<image width="176" height="136" alt="(this slide left blank for use as a whiteboard)">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-2.png</image>
<image width="176" height="136" alt="(this slide left blank for use as a whiteboard)">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-3.png</image>
</images>
</preview>
</format>
</playback>
</recording>
</recordings>
</response>
GET
publishRecordings
Publish and unpublish recordings for a given recordID (or set of record IDs).
Resource URL:
Parameters:
Param Name | Type | Description |
---|---|---|
recordID (required) | String | A record ID for specify the recordings to apply the publish action. It can be a set of record IDs separated by commas. |
publish (required) | String | The value for publish or unpublish the recording(s). Available values: true or false. |
Example Requests:
- http://yourserver.com/bigbluebutton/api/publishRecordings?recordID=record123&publish=true&checksum=1234
- http://yourserver.com/bigbluebutton/api/publishRecordings?recordID=record123,recordABC&publish=true&checksum=wxyz
Example Response:
<response>
<returncode>SUCCESS</returncode>
<published>true</published>
</response>
GET
deleteRecordings
Delete one or more recordings for a given recordID (or set of record IDs).
Resource URL:
http://yourserver.com/bigbluebutton/api/deleteRecordings?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
recordID (required) | String | A record ID for specify the recordings to delete. It can be a set of record IDs separated by commas. |
Example Requests:
- http://yourserver.com/bigbluebutton/api/deleteRecordings?recordID=record123&checksum=1234
- http://yourserver.com/bigbluebutton/api/deleteRecordings?recordID=record123,recordABC&checksum=wxyz
Example Response:
<response>
<returncode>SUCCESS</returncode>
<deleted>true</deleted>
</response>
GET
POST
updateRecordings
Update metadata for a given recordID (or set of record IDs). Available since version 1.1
Resource URL:
Parameters:
Param Name | Type | Description |
---|---|---|
recordID (required) | String | A record ID for specify the recordings to apply the publish action. It can be a set of record IDs separated by commas. |
meta | String | You can pass one or more metadata values to be updated. The format of these parameters is the same as the metadata passed to the create call. For more information see the docs for the create call. When meta_parameter=NOT EMPTY and meta_parameter exists its value is updated, if it doesn’t exist, the parameter is added. When meta_parameter=, and meta_parameter exists the key is removed, when it doesn’t exist the action is ignored. |
Example Requests:
Example Response:
<response>
<returncode>SUCCESS</returncode>
<updated>true</updated>
</response>
GET
POST
getRecordingTextTracks
Get a list of the caption/subtitle files currently available for a recording. It will include information about the captions (language, etc.), as well as a download link. This may be useful to retrieve live or automatically transcribed subtitles from a recording for manual editing.
Resource URL:
GET http://yourserver.com/bigbluebutton/api/getRecordingTextTracks?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
recordID (required) | String | A single recording ID to retrieve the available captions for. (Unlike other recording APIs, you cannot provide a comma-separated list of recordings.) |
Example Response:
An example response looks like the following:
{
"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"
}
]
}
}
The track object has the following attributes:
kind
: Indicates the intended use of the text track. The value will be one of the following strings: subtitles
captions
: The meaning of these values is defined by the HTML5 video element, see the MDN docs for details. Note that the HTML5 specification defines additional values which are not currently used here, but may be added at a later date.
lang : The language of the text track, as a language tag. See RFC 5646 for details on the format, and the Language subtag lookup for assistance using them. It will usually consist of a 2 or 3 letter language code in lowercase, optionally followed by a dash and a 2-3 letter geographic region code (country code) in uppercase.
label : A human-readable label for the text track. This is the string displayed in the subtitle selection list during recording playback.
source : Indicates where the track came from. The value will be one of the following strings:
- live - A caption track derived from live captioning performed in a BigBlueButton.
- automatic - A caption track generated automatically via computer voice recognition.
- upload - A caption track uploaded by a 3rd party.
href : A link to download this text track file. The format will always be WebVTT (text/vtt mime type), which is similar to the SRT format.
The timing of the track will match the current recording playback video and audio files. Note that if the recording is edited (adjusting in/out markers), tracks from live or automatic sources will be re-created with the new timing. Uploaded tracks will be edited, but this may result in data loss if sections of the recording are removed during edits.
Errors
: In addition to the standard BigBlueButton checksum error, this API call can return the following errors in <messageKey>
when returncode is FAILED:
missingParameter : A required parameter is missing.
noRecordings : No recording was found matching the provided recording ID.
POST
putRecordingTextTrack
Upload a caption or subtitle file to add it to the recording. If there is any existing track with the same values for kind and lang, it will be replaced.
Note that this api requires using a POST request. The parameters listed as GET parameters must be included in the request URI, and the actual uploaded file must be included in the body of the request in the multipart/form-data format.
Note that the standard BigBlueButton checksum algorithm must be performed on the GET parameters, but that the body of the request (the subtitle file) is not checksummed.
This design is such that a web application could generate a form with a signed url, and display it in the browser with a file upload selection box. When the user submits the form, it will upload the track directly to the recording api. The API may be used programmatically as well, of course.
This API is asynchronous. It can take several minutes for the uploaded file to be incorporated into the published recording, and if an uploaded file contains unrecoverable errors, it may never appear.
Resource URL:
POST http://yourserver.com/bigbluebutton/api/putRecordingTextTrack
Parameters:
Param Name | Type | Description |
---|---|---|
recordID (required) | String | A single recording ID to retrieve the available captions for. (Unlike other recording APIs, you cannot provide a comma-separated list of recordings.) |
kind (required) | String | Indicates the intended use of the text track. See the getRecordingTextTracks description for details. Using a value other than one listed in this document will cause an error to be returned. |
lang (required) | String | Indicates the intended use of the text track. See the getRecordingTextTracks description for details. Using a value other than one listed in this document will cause an error to be returned. |
label (required) | String | A human-readable label for the text track. If not specified, the system will automatically generate a label containing the name of the language identified by the lang parameter. |
POST Body:
If the request has a body, the Content-Type header must specify multipart/form-data. The following parameters may be encoded in the post body.
file:
(Type Binary Data, Optional) Contains the uploaded subtitle or caption file. If this parameter is missing, or if the POST request has no body, then any existing text track matching the kind and lang specified will be deleted. If known, the uploading application should set the Content-Type
to a value appropriate to the file format. If Content-Type is unset, or does not match a known subtitle format, the uploaded file will be probed to automatically detect the type.
Multiple types of subtitles are accepted for upload, but they will be converted to the WebVTT format for display.
The size of the request is limited (TODO: determine the limit maybe 8MB?)
The following types of subtitle files are accepted:
- SRT (SubRip Text), including basic formatting.
- SRT does not have a standard mime type, but application/x-subrip is accepted.
- SSA or ASS (Sub Station Alpha, Advanced Sub Station). Most formatting will be discarded, but basic inline styles (bold, italic, etc.) may be preserved.
- SSA/ASS does not have a standard mime type.
- WebVTT. Uploaded WebVTT files will be used as-is, but note that browser support varies, so including REGION or STYLE blocks is not recommended.
The WebVTT mime type is text/vtt
.
Errors
In addition to the standard BigBlueButton checksum error, this API call can return the following errors in <messageKey>
when returncode is FAILED:
missingParameter : A required parameter is missing.
noRecordings : No recording was found matching the provided recording ID.
invalidKind : The kind parameter is not set to a permitted value.
invalidLang : The lang parameter is not a well-formed language tag.
The uploaded text track is not validated during upload. If it is invalid, it will be ignored and the existing subtitles will not be replaced.
Success
{
"response": {
"messageKey": "upload_text_track_success",
"message": "Text track uploaded successfully",
"recordId": "baz",
"returncode": "SUCCESS"
}
}
Failed
{
"response": {
"messageKey": "upload_text_track_failed",
"message": "Text track upload failed.",
"recordId": "baz",
"returncode": "SUCCESS"
}
}
Or
{
"response": {
"message": "Empty uploaded text track.",
"messageKey": "empty_uploaded_text_track",
"returncode": "FAILED"
}
}
Missing parameter error
{
"response": {
"messageKey": "paramError",
"message": "Missing param checksum.",
"returncode": "FAILED"
}
}
GET
sendChatMessage
This call enables you to send a message to the public chat of a running meeting.
Resource URL:
http://yourserver.com/bigbluebutton/api/sendChatMessage?[parameters]&checksum=[checksum]
Parameters:
Param Name | Type | Description |
---|---|---|
meetingID (required) | String | The meeting ID that identifies the meeting you are attempting to send a message. |
message (required) | String | The message you want to send to the public chat of the meeting. |
userName | String | Optional param to set the name that will be showed as the author of the message. Default: |
Example Requests:
Example Response:
<response>
<returncode>SUCCESS</returncode>
<messageKey></messageKey>
<message></message>
</response>
API Sample Code
BigBlueButton provides API Sample Codes so you can integrated easily with your application. Feel free to contribute and post your implementation of the API in other language code in the bigbluebutton-dev mailing list.
PHP
There is stable PHP library in BigBlueButton PHP API.
You need to enable the "allow_url_fopen" to "On" in your php.ini file so this example can work. Simply add/replace to your php.ini file:
allow_url_fopen = On
For more examples of using PHP, see the source for the Moodle and WordPress integrations.
Ruby
See the following bigbluebutton-api-ruby gem created by the good folks at Mconf.
Testing API Calls with API Mate
To help you create/test valid API calls against your BigBlueButton server, use the excellent API Mate to interactively create API calls. API Mate generates the checksums within the browser (no server component needed) so you can use it to test API calls against a local BigBlueButton server.
If you're developing new API calls or adding parameters on API calls, you can still use the API Mate to test them. Just scroll the page down or type "custom" in the parameter filter and you'll see the inputs where you can add custom API calls or user metadata. New API calls will appear in the list of API links and new parameters will be added to all the API links.
If your using API Mate to test recordings and want to query by meetingID
, be sure to clear the recordID
field first. BigBlueButton's API supports querying for recordings by either value, but not both at the same time.
Support for JSON/JSONP
- It would be very nice to optionally allow JSON responses, and to support JSONP. This might allow for simpler integrations, even within static or almost-static webpages using JavaScript as the primary integration language. It should not be assumed that all users will be running custom software on a server and be able to process XML responses, etc.
- This being said, even within JavaScript there are simple ways to make the API call and process the returned XML (using jQuery and $.xml2json, for example)
Meeting event callbacks
This may actually even be called a “reverse API” - where we define an interface that the third- party application can implement to be notified of events. This would not be necessary for the first version of the API, but would be a nice feature for future enhancements. More details:
When major events happen within meetings, it would be very helpful to provide a way for third-party applications to be notified of these events. For instance, when a user joins a conference, they will presumably be joining through the third-party app. However, when they leave the conference, the app may have certain auditing that it needs to do to record their disconnect time, etc. If BigBlueButton could make some callback to the application, this would assist in such scenarios.
For example, the application may be able to register a URL that BigBlueButton would call with status updates. BigBlueButton would define an API that such an app would be required to implement at that URL. For example, BigBlueButton could call:
- http://third-party-app/bbb-integ.php?event=meetingEnded&meetingID=abcd
- http://third-party-app/bbb-integ.php?event=userLeft&userID=1234
- http://third-party-app/bbb-integ.php?event=meetingEnded&meetingID=abcd
Other Topics
Supported Document Types
PDF Documents
- PDF:
Office Documents
- Microsoft Word:
- .doc
- .docx
- Microsoft Excel:
- .xls
- .xlsx
- Microsoft PowerPoint:
- .ppt
- .pptx
- OpenDocument Formats:
- .odt (Text Document)
- .ods (Spreadsheet)
- .odp (Presentation)
- .odg (Graphics)
Image Files
- Common Image Formats:
- .jpg
- .jpeg
- .png
- .webp
- .svg
Text Files
- Rich Text Format:
- .rtf
- Plain Text:
- .txt
All these valid formats are also present in a list in the back-end and in the front-end if more details are needed.