Overview

    This document describes the BigBlueButton application programming interface (API).

    For developers, this API enables you to

    • create meetings
    • join meetings
    • end meetings
    • 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:

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

    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 bigbluebutton.properties file. On a BigBlueButton 2.0 server, this file is located at

    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties
    

    On BigBlueButton 2.2 server, this file is located at

    /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties
    

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

    #----------------------------------------------------
    # Default dial access number
    defaultDialAccessNumber=613-555-1234
    
    # Default Guest Policy
    # Valid values are ALWAYS_ACCEPT, ALWAYS_DENY, ASK_MODERATOR
    #
    defaultGuestPolicy=ALWAYS_ACCEPT
    
    #
    #----------------------------------------------------
    # Default welcome message to display when the participant joins the web
    # conference. This is only used for the old scheduling which will be
    # removed in the future. Use the API to create a conference.
    #
    # If the message contains characters not in ISO-8859-1 character sets
    # they must be properly escaped to unicode characters. An easy way to
    # do this is running the native2ascii command setting UTF8 encoding and
    # passing this file's path as input and output parameters, e.g.:
    #
    # native2ascii -encoding UTF8 bigbluebutton.properties bigbluebutton.properties
    #
    defaultWelcomeMessage=Welcome to <b>%%CONFNAME%%</b>!<br><br>For help on using BigBlueButton see these (short) <a href="event:http://www.bigbluebutton.org/html5"><u>tutorial videos</u></a>.<br><br>To join the audio bridge click the phone button.  Use a headset to avoid causing background noise for others.
    defaultWelcomeMessageFooter=This server is running <a href="http://docs.bigbluebutton.org/" target="_blank"><u>BigBlueButton</u></a>.
    
    # Default maximum number of users a meeting can have.
    # Current default is 0 (meeting doesn't have a user limit).
    defaultMaxUsers=0
    
    # Default duration of the meeting in minutes.
    # Current default is 0 (meeting doesn't end).
    defaultMeetingDuration=0
    
    # Number of minutes elapse of no activity before
    # ending the meeting. Default zero (0) to disable
    # check.
    maxInactivityTimeoutMinutes=0
    
    # Number of minutes to logout client if user
    # isn't responsive
    clientLogoutTimerInMinutes=0
    
    # Send warning to moderators to warn that
    # meeting would be ended due to inactivity
    warnMinutesBeforeMax=5
    
    # End meeting if no user joined within
    # a period of time after meeting created.
    meetingExpireIfNoUserJoinedInMinutes=5
    
    # Number of minutes to end meeting when
    # the last user left.
    meetingExpireWhenLastUserLeftInMinutes=1
    
    # User inactivity audit timer interval.
    userInactivityInspectTimerInMinutes=0
    
    # Number of minutes to consider a user inactive.
    # iSend warning message to client to check if really inactive.
    userInactivityThresholdInMinutes=30
    
    # Number of minutes for user to respond to inactivity
    # warning before being logged out.
    userActivitySignResponseDelayInMinutes=5
    
    # Disable recording by default. 
    #   true - don't record even if record param in the api call is set to record
    #   false - when record param is passed from api, override this default
    disableRecordingDefault=false
    
    # Start recording when first user joins the meeting.
    # For backward compatibility with 0.81 where whole meeting
    # is recorded.  
    autoStartRecording=false
    
    # Allow the user to start/stop recording.
    allowStartStopRecording=true
    
    # Allow webcams streaming reception only to and from moderators
    webcamsOnlyForModerator=false 
    
    # Mute the meeting on start
    muteOnStart=false
    
    # Unmute users
    # Gives moderators permisson to unmute other users
    allowModsToUnmuteUsers=false
    
    # Saves meeting events even if the meeting is not recorded
    keepEvents=false
    
    # Default Lock Settings
    lockSettingsDisableCam=false
    lockSettingsDisableMic=false
    lockSettingsDisablePrivateChat=false
    lockSettingsDisablePublicChat=false
    lockSettingsDisableNote=false
    lockSettingsLockedLayout=false
    lockSettingsLockOnJoin=true
    lockSettingsLockOnJoinConfigurable=false
    
    # Unmute users
    # Gives moderators permisson to unmute other users
    allowModsToUnmuteUsers=false
    
    #----------------------------------------------------
    # This URL is where the BBB client is accessible. When a user sucessfully
    # enters a name and password, she is redirected here to load the client.
    bigbluebutton.web.serverURL=https://bbb.example.com
    

    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 an 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.
    getDefaultConfigXML Gets the default config.xml (these settings configure the BigBlueButton client for each user).
    setConfigXML Add a custom config.xml to an existing meeting.
    join Join a new user to an existing meeting.
    end Ends meeting.

    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.
    updateRecordings 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 bigbluebutton.properties.

    Resource URL:

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

    Parameters:

    Param Name Required / Optional Type Description
    name Optional String A name for the meeting.
    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 Optional (recommended) 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 randomally generated attendeePW password for the meeting.
    moderatorPW Optional (recommended) 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.
    welcome Optional 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 Optional 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 Optional String Voice conference number that participants enter to join the voice conference. The default pattern for this is a 5-digit number. This is the PIN that a dial-in user must enter to join the conference.

    If you want to change this pattern, you have to edit FreeSWITCH dialplan and defaultNumDigitsForTelVoice of bigbluebutton.properties. When using the default setup, we recommend you always pass a 5-digit voiceBridge parameter.

    If you don’t pass a value for voiceBridge, then users will not be able to join a voice conference for the session. (see FAQ entry Users do not appear in listeners window. See Add a phone number to the conference.
    webVoice Optional String Voice conference alphanumeric that participants enter to join the voice conference.

    Using this parameter requires custom configuration of the FreeSWITCH server. See Add a phone number to the conference.
    maxParticipants Optional Number Set the maximum number of users allowed to joined the conference at the same time.
    logoutURL Optional 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 Optional 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 sesssion; 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 Optional 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 the first person joins. 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 Required(Breakout Room) Boolean Must be set to true to create a breakout room.
    parentMeetingID Required(Breakout Room) String Must be provided when creating a breakout room, the parent room must be running.
    sequence Required(Breakout Room) Number The sequence number of the breakout room.
    freeJoin Optional(Breakout Room) Boolean If set to true, the client will give the user the choice to choose the breakout rooms he wants to join.
    meta Optional 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 Optional String Display a message to all moderators in the public chat.

    The value is interpreted in the same way as the welcome parameter.
    autoStartRecording Optional 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 Optional 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 Optional Boolean Setting webcamsOnlyForModerator=true will cause all webcams shared by viewers during this meeting to only appear for moderators (added 1.1)
    logo Optional String Setting logo=http://www.example.com/my-custom-logo.png will replace the default logo in the Flash client. (added 2.0)
    bannerText Optional String Will set the banner text in the client. (added 2.0)
    bannerColor Optional String Will set the banner background color in the client. The required format is color hex #FFFFFF. (added 2.0)
    copyright Optional String Setting copyright=My custom copyright will replace the default copyright on the footer of the Flash client. (added 2.0)
    muteOnStart Optional Boolean Setting muteOnStart=true will mute all users when the meeting starts. (added 2.0)
    allowModsToUnmuteUsers Optional Boolean Default allowModsToUnmuteUsers=false. Setting to allowModsToUnmuteUsers=true will allow moderators to unmute other users in the meeting. (added 2.2)
    lockSettingsDisableCam Optional Boolean Default lockSettingsDisableCam=false. Setting lockSettingsDisableCam=true will prevent users from sharing their camera in the meeting. (added 2.2)
    lockSettingsDisableMic Optional Boolean Default lockSettingsDisableMic=false. Setting to lockSettingsDisableMic=true will only allow user to join listen only. (added 2.2)
    lockSettingsDisablePrivateChat Optional Boolean Default lockSettingsDisablePrivateChat=false. Setting to lockSettingsDisablePrivateChat=true will disable private chats in the meeting. (added 2.2)
    lockSettingsDisablePublicChat Optional Boolean Default lockSettingsDisablePublicChat=false. Setting to lockSettingsDisablePublicChat=true will disable public chat in the meeting. (added 2.2)
    lockSettingsDisableNote Optional Boolean Default lockSettingsDisableNote=false. Setting to lockSettingsDisableNote=true will disable notes in the meeting. (added 2.2)
    lockSettingsLockedLayout Optional Boolean Default lockSettingsLockedLayout=false. Setting to lockSettingsLockedLayout=true will lock the layout in the meeting. (added 2.2)
    lockSettingsLockOnJoin Optional Boolean Default lockSettingsLockOnJoin=true. Setting to lockSettingsLockOnJoin=false will not apply lock setting to users when they join. (added 2.2)
    lockSettingsLockOnJoinConfigurable Optional Default lockSettingsLockOnJoinConfigurable=false. Setting to lockSettingsLockOnJoinConfigurable=true will allow applying of lockSettingsLockOnJoin param. (added 2.2)  
    guestPolicy Optional String Default guestPolicy=ALWAYS_ACCEPT. 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.

    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>
    

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

    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

    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
    

    Recording ready callback URL

    Note: This callback will be in BigBlueButton 2.0-RC7

    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_bn-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 Required/Optional 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 The password that this attendee is using. If the moderator password is supplied, he will be given moderator status (and the same for attendee password, etc)
    createTime Optional 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 Optional 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 Optional 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.
    configToken Optional String The token returned by a setConfigXML API call. This causes the BigBlueButton client to load the config.xml associated with the token (not the default config.xml)
    defaultLayout Optional String The layout name to be loaded first when the application is loaded.
    avatarURL Optional String The link for the user’s avatar to be displayed when displayAvatar in config.xml is set to true.
    redirect Optional (Experimental) String The default behaviour of the JOIN API is to redirect the browser to the Flash client when the JOIN call succeeds. There have been requests if it’s possible to embed the Flash 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.
    clientURL Optional (Experimental) String Some third party apps what to display their own custom client. These apps can pass the URL containing the custom client and when redirect is not set to false, the browser will get redirected to the value of clientURL.
    joinViaHtml5 Optional String Set to “true” to force the HTML5 client to load for the user.
    guest Optional String Set to “true” to indicate that the user is a guest.

    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 only an XML response for this call if the redirect parameter is set to true. 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>
    

    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 Required/Optional 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 Required/Optional Type Description
    meetingID Required String The meeting ID that identifies the meeting you are attempting to end.
    password Required String The moderator password for this meeting. You can not end a meeting using the attendee password.

    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>
    

    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 Required/Optional Type Description
    meetingID Required String The meeting ID that identifies the meeting you are attempting to check on.
    password Deprecated in v1.0 String The moderator password for this meeting. You can not get the meeting information using the attendee password.

    Example Requests:

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

    Retrieves the recordings that are available for playback for a given meetingID (or set of meeting IDs).

    Resource URL:

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

    Parameters:

    Param Name Required / Optional Type Description
    meetingID Optional 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 Optional 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 Optional 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 Optional 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.

    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

    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 Required / Optional 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>
    

    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 Required / Optional 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 Required / Optional 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 Optional 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>
    

    getDefaultConfigXML

    Retrieve the default config.xml. This call enables a 3rd party application to get the current config.xml, modify it’s parameters, and use setConfigXML to store it on the BigBlueButton server (getting a reference token to the new config.xml), then using the token in as a parameter in the join URL to override the default config.xml.

    Resource URL:

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

    setConfigXML

    Associate a custom config.xml file with the current session. This call returns a token that can later be passed as a parameter to a join URL. When passed as a parameter, the BigBlueButton client will use the associated config.xml for the user instead of using the default config.xml. This enables 3rd party applications to provide user-specific config.xml files.

    Resource URL:

    POST http://yourserver.com/bigbluebutton/api/setConfigXML

    Parameters:

    Param Name Required / Optional Type Description
    meetingID Required String A meetingID to an active meeting
    configXML Required String A valid config.xml file

    Parameter Encoding:

    This API request encodes the parameters in the body of a post request, using the content type application/x-www-form-urlencoded (The Content-Type header must be present or the parameters will not be processed). As a result, the calculation for the checksum parameter is done differently than in other types of requests.

    Similarly like for GET requests, the checksum is calculated by taking the SHA-1 hash of a string generated by concatenating the method name, parameter string, and shared secret. However, the parameter string must be generated in a very specific format to ensure that changes in the body encoding won’t invalidate the checksum.

    To generate the parameter string field, do the following steps:

    • Sort the parameters in ASCII order by the parameter name. (Parameters with duplicate names are not permitted.)
    • URL-encode the parameter values according to the following specification: The characters “a” through “z”, “A” through “Z”, “0” through “9”, and “.”, “-”, “*”, “_” remain the same. The space character “ ” is encoded as a plus sign “+”. All other characters must be encoded as UTF-8, and then are converted bytewise to percent-encoding. This matches the default encoding method of java.net.URLEncoder and Ruby’s URI.encode_www_form_component. Other languages probably also have functions which match this specification.
    • Join the parameter name and URL-encoded parameter value together with the “=” character.
    • Concatenate all the parameter name/value pairs in order, separating them with the “&” character.

    To verify the checksum, the BigBlueButton server will decode the parameters from the message body, then use the same algorithm as described above to calculate the checksum. As a result:

    • You are not required to have parameters in the same order in the message body as they were in the encoded parameter string.
    • The checksum parameter can be in any position.
    • You are not required to use the same URL-encoding method in the message body as the encoded parameter string. For example, using %20 instead of + for a space is OK.

    Example Requests:

    The config.xml is sent as part of a POST request. The body of the POST request must contain three parameters: meetingID, configXML and checksum. The meetingID is the meeting to which this config.xml will be associated to (the meeting must have been created previously), the configXML is the content of the config.xml file, and the checksum is the signature of this call, calculated as described above. An example showing how to calculate the checksum:

    • Method name: setConfigXML
    • Parameters: meetingID=random-8228800 and configXML=<config><modules><localeversion supressWarning="false">0.9.0</localeversion></modules></config>
    • Encoded parameter string: configXML=%3Cconfig%3E%3Clocaleversion+suppressWarning%3D%22false%22%3E0.9.0%3C%2Flocaleversion%3E%3C%2Fmodules%3E%3C%2Fconfig%3E&meetingID=random-8228800
    • Shared secret: aae06642a13942004fd83b3ba6e4o9s8
    • Final string: setConfigXMLconfigXML=%3Cconfig%3E%3Clocaleversion+suppressWarning%3D%22false%22%3E0.9.0%3C%2Flocaleversion%3E%3C%2Fmodules%3E%3C%2Fconfig%3E&meetingID=random-8228800aae06642a13942004fd83b3ba6e4o9s8
    • The calculated checksum is 51db6f55ffa080f42f5727386beb66adb4e5cf81
    • The final parameter string that will be used in the message body is checksum=51db6f55ffa080f42f5727386beb66adb4e5cf81&configXML=%3Cconfig%3E%3Clocaleversion+suppressWarning%3D%22false%22%3E0.9.0%3C%2Flocaleversion%3E%3C%2Fmodules%3E%3C%2Fconfig%3E&meetingID=random-8228800 (Note that the order of the parameters does not matter here.)

    See also this API source example from the API demos for making a call to setConfigXML.

    Example Response:

    <response>
      <returncode>SUCCESS</returncode>
      <token>6lwBf1TX</token>
    </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 Required / Optional 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 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 Required / Optional 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 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.

    JSP

    The JSP library included with the BigBlueButton API demos is the reference implementation of the BigBlueButton API. We use this library to test and demonstrate how to use the API. You can try out the demos on the BigBlueButton demo server. See full source for the API demos

    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

    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.

    Desired Future Features

    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

    We are already announcing events such as this within BigBlueButton through Redis Pubsub to communicate between the Red5 apps where these events originate and the API. It would probably not be very difficult to register additional listeners through the Spring Integration configuration that will make these HTTP calls for us for each event.