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

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 as myconfig.xml.
• create - Added three parameters: moderatorOnlyMessage to display message only visible to moderators and autoStartRecording/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, and muteOnStart.
• 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 to meetingKeepEvents, removed joinViaHtml5, added endWhenNoModeratorDelayInMinutes.
• 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, and moderatorPW must be between 2 and 64 characters long
  • meetingID must be between 2 and 256 characters long and cannot contain commas
• join - Added role, excludeFromDashboard.

Updated in 2.5:

• create - Added: meetingCameraCap, groups, disabledFeatures, meetingExpireIfNoUserJoinedInMinutes, meetingExpireWhenLastUserLeftInMinutes, preUploadedPresentationOverrideDefault; Deprecated: learningDashboardEnabled, breakoutRoomsEnabled, virtualBackgroundsDisabled.

• insertDocument endopoint was first introduced

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 accessibile 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 accessibile 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 2.5 support for additional hashing algorithms, besides sha1 and sha256, were added. These include sha384 and sha512. The supportedChecksumAlgorithms property in bigbluebutton.properties 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.

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:

1. 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
2. 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
3. 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
4. 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
5. 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

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.

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 call DigestUtils.shaHex(string + sharedSecret)
• PHP
  • simply call sha1(string . sharedSecret)

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

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. Added in 2.4: This parameter is now required.
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 (deprecated)	String	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. Deprecated: If the role parameter is used on the join URL, the attendeePW is unused.
moderatorPW (deprecated)	String	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. Deprecated: If the role parameter is used on the join URL, the moderatorPW is unused.
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 (required)	String	Must be provided when creating a breakout room, the parent room must be running.
sequence (required)	Number	The sequence number of the breakout room.
freeJoin (required)	Boolean	If set to true, the client will give the user the choice to choose the breakout rooms he wants to join.
breakoutRoomsPrivateChatEnabled (required)	Boolean	If set to false, the private chat will be disabled in breakout rooms. Default: true
breakoutRoomsRecord (required)	Boolean	If set to false, breakout rooms will not be recorded. Default: false
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: false
lockSettingsDisableCam	Boolean	Setting true will prevent users from sharing their camera in the meeting. (added 2.2) Default: false
lockSettingsDisableMic	Boolean	Setting to true will only allow user to join listen only. (added 2.2) Default: false
lockSettingsDisablePrivateChat	Boolean	Setting to true will disable private chats in the meeting. (added 2.2) Default: false
lockSettingsDisablePublicChat	Boolean	Setting to true will disable public chat in the meeting. (added 2.2) Default: false
lockSettingsDisableNotes	Boolean	Setting to true will disable notes in the meeting. (added 2.2) Default: false
lockSettingsHideUserList	Boolean	Setting to true will prevent viewers from seeing other viewers in the user list. (added 2.2) Default: false
lockSettingsLockOnJoin	Boolean	Setting to false will not apply lock setting to users when they join. (added 2.2) Default: true
lockSettingsLockOnJoinConfigurable	Boolean	Setting to true will allow applying of lockSettingsLockOnJoin. Default: false
lockSettingsHideViewersCursor	Boolean	Setting to true will prevent viewers to see other viewers cursor when multi-user whiteboard is on. (added 2.5) Default: false
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: ALWAYS_ACCEPT
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: false
endWhenNoModerator	Boolean	Default endWhenNoModerator=false. If endWhenNoModerator is true the meeting will end automatically after a delay - see endWhenNoModeratorDelayInMinutes (added in 2.3) Default: false
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: 1
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, MEDIA_ONLY Default: CUSTOM_LAYOUT
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: 2
allowModsToEjectCameras	Boolean	Setting to true will allow moderators to close other users cameras in the meeting. (added 2.4) Default: false
allowRequestsWithoutSession	Boolean	Setting to true will allow users to join meetings without session cookie's validation. (added 2.4.3) Default: false
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: 3
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: 0
meetingExpireIfNoUserJoinedInMinutes	Number	Automatically end meeting if no user joined within a period of time after meeting created. (added 2.5) Default: 5
meetingExpireWhenLastUserLeftInMinutes	Number	Number of minutes to automatically end meeting after last user left. (added 2.5) Setting to 0 will disable this function. Default: 1
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: id - String with group unique id. name - String with name of the group (optional). roster - Array with IDs of the users. E.g: [ {"id":'1',name:'GroupA',roster:['1235']}, {"id":'2',name:'GroupB',roster:['2333','2335']}, {"id":'3',roster:[]} ]
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. Available options to disable: breakoutRooms - Breakout Rooms captions - Closed Caption chat - Chat (Public and Private) privateChat - Private Chat deleteChatMessage - Delete a Chat Message (moderators or author) editChatMessage - Edit a Chat Message (only author) replyChatMessage - Reply to a Chat Message chatMessageReactions - Send Reactions to a chat message downloadPresentationWithAnnotations - Annotated presentation download downloadPresentationConvertedToPdf - Converted presentation download (if BigBlueButton had to convert to PDF) downloadPresentationOriginalFile - Original presentation download snapshotOfCurrentSlide - Allow snapshot of the current slide externalVideos - Share an external video importPresentationWithAnnotationsFromBreakoutRooms - Capture breakout presentation importSharedNotesFromBreakoutRooms - Capture breakout shared notes layouts - Layouts (allow only default layout) learningDashboard - Learning Analytics Dashboard learningDashboardDownloadSessionData - Learning Analytics Dashboard Download Session Data (prevents the option to download) polls - Polls screenshare - Screen Sharing sharedNotes - Shared Notes virtualBackgrounds - Virtual Backgrounds customVirtualBackgrounds - Virtual Backgrounds Upload liveTranscription - Live Transcription presentation - Presentation cameraAsContent - Enables/Disables camera as a content timer - Disables timer infiniteWhiteboard - Infinite Whiteboard (added in BigBlueButton 3.0)
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: true
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: false
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)
presentationConversionCacheEnabled	Boolean	Parameter to decide whether to use the caching system in a S3-based storage system for presentation assets per meeting. If this parameter is true, the other settings related to the caching feature must be configured properly (see section Configure S3-based cache for presentation assets).
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: false
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	Boolean	Whether to allow clientSettingsOverride to be included in the body of a POST request. Because the body of the post request is not signed by the checksum, this parameter is set to false by default. If you set this to true, you must make sure that the signed parameters of the create API request are not visible to users. Added: 3.0.0-alpha.1 Default: false
clientSettingsOverride	JSON	A data structure containing settings which override values from the HTML5 client's settings.yml file. This data can also be provided in the body of a POST request, see clientSettingsOverride for details. Added: 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: false
pluginManifests	JSON	A list of the BigBlueButton client plugins you want included for the specific session (merged with the list in /etc/bigbluebutton/bbb-web.properties and duplicates dropped) pluginManifests=[{"url":"https://someserver.com/plugins/bbb-plugin-pick-random-user/manifest.json"}]
maxNumPages	Number	Maximum number of pages allowed for an uploaded presentation. Default: 200

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 usefull 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).

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. For a complete example of the pre-upload slides check the following demos: demo7 and demo8

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 the internalMeetingId 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.

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 (deprecated) (required)	String	This password value is used to determine the role of the user. It must match either the moderator or attendee password. Deprecated: Use the role parameter instead to directly set the user's role. If the role parameter is passed, then the password parameter is not required.
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).
firstName	String	The user's first name portion of "fullname". It is used for sorting purposes; it will not be displayed in the user list. This property is useful if the "fullname" is comprised of several words or if there are title/role/credentials which should be ignored when sorting.
lastName	String	The user's last name portion of "fullname". It is used for sorting purposes; it will not be displayed in the user list. This property is useful if the "fullname" is comprised of several words or if there are title/role/credentials which should be ignored when sorting.
webcamBackgroundURL	String	The URL of an image to use as the user's webcam background. Server-wide defaults can be enabled/disabled and set with useDefaultWebcamBackground and defaultWebcamBackgroundURL in bigbluebutton.properties. Added: 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.
logoutURL	String	A custom URL to redirect client when the user click on OK button in the meeting ended screen. By default users are redirected to the meeting's default logout URL.
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, MEDIA_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>

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>'

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.

end

Use this to forcibly end a meeting and kick all participants out of the meeting.

Resource URL:

• http://yourserver.com/bigbluebutton/api/end?[parameters]&checksum=[checksum]

Parameters:

Param Name	Type	Description
meetingID (required)	String	The meeting ID that identifies the meeting you are attempting to end.
password (deprecated)	String	Deprecated: In older BigBlueButton versions, this parameter had to be set to the moderator password for the meeting. It is no longer required.

Example Requests:

• http://yourserver.com/bigbluebutton/api/end?meetingID=1234567890&password=mp&checksum=1234

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.

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:

• http://yourserver.com/bigbluebutton/api/getMeetingInfo?[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/getMeetingInfo?meetingID=test01&checksum=1234

Example Response:

<response>
  <returncode>SUCCESS</returncode>
  <meetingName>Demo Meeting</meetingName>
  <meetingID>Demo Meeting</meetingID>
  <internalMeetingID>183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531240585189</internalMeetingID>
  <createTime>1531240585189</createTime>
  <createDate>Tue Jul 10 16:36:25 UTC 2018</createDate>
  <voiceBridge>70066</voiceBridge>
  <dialNumber>613-555-1234</dialNumber>
  <attendeePW>ap</attendeePW>
  <moderatorPW>mp</moderatorPW>
  <running>true</running>
  <duration>0</duration>
  <hasUserJoined>true</hasUserJoined>
  <recording>false</recording>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
  <startTime>1531240585239</startTime>
  <endTime>0</endTime>
  <participantCount>2</participantCount>
  <listenerCount>1</listenerCount>
  <voiceParticipantCount>1</voiceParticipantCount>
  <videoCount>1</videoCount>
  <maxUsers>20</maxUsers>
  <moderatorCount>1</moderatorCount>
  <attendees>
    <attendee>
      <userID>w_2wzzszfaptsp</userID>
      <fullName>stu</fullName>
      <role>VIEWER</role>
      <isPresenter>false</isPresenter>
      <isListeningOnly>true</isListeningOnly>
      <hasJoinedVoice>false</hasJoinedVoice>
      <hasVideo>false</hasVideo>
      <clientType>FLASH</clientType>
    </attendee>
    <attendee>
      <userID>w_eo7lxnx3vwuj</userID>
      <fullName>mod</fullName>
      <role>MODERATOR</role>
      <isPresenter>true</isPresenter>
      <isListeningOnly>false</isListeningOnly>
      <hasJoinedVoice>true</hasJoinedVoice>
      <hasVideo>true</hasVideo>
      <clientType>HTML5</clientType>
    </attendee>
  </attendees>
  <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>

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>

getRecordings

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 ≥ 0	The starting index for returned recordings.
limit	Integer [ 1 .. 100 ]	The maximum number of recordings to be returned per request.

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>

publishRecordings

Publish and unpublish recordings for a given recordID (or set of record IDs).

Resource URL:

• http://yourserver.com/bigbluebutton/api/publishRecordings?[parameters]&checksum=[checksum]

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)	Boolean	Either true to publish the recording(s), or false to unpublish the recording(s).

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>

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>

updateRecordings

Update metadata for a given recordID (or set of record IDs). Available since version 1.1

Resource URL:

• http://yourserver.com/bigbluebutton/api/updateRecordings?[parameters]&checksum=[checksum]

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:

• http://yourserver.com/bigbluebutton/api/updateRecordings?recordID=record123&meta_Presenter=Jane%20Doe,meta_category=FINANCE,meta_TERM=Fall2016&checksum=1234

Example Response:

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

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.

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"
  }
}

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 custom parameters. 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