Overview

    This document describes the BigBlueButton API available for integration with 3rd-party applications.

    The API is implemented with developer in mind. To make and API call a BigBlueButton, your 3rd-party application makes HTTP requests to a URL. All API calls include a checksum that signs the parameters with a shared secret (called salt by BigBlueButton).

    The BigBlueButton server returns an XML response to all API calls.

    The API implementation bigbluebutton-web component, which has been written using the Grails framework.

    Updates to API in BigBlueButton 0.9.0

    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 fileds on the returned XML
    • getMeetingsInfo - Added fields on the returned XML
    • getRecordings - Added meta parameter to filter retured results

    For more details see 1.0 API Extensions.

    API Data Types

    In the documentation below, various parameters are described with the data types String, Boolean, Number. Here are the definitions for these types:

    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 enabled 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 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 HTTP requests to the BigBlueButton server’s API end point.

    You can retrieve the API parameters (API endpoint and shared secret) using the command

    bbb-conf --secret
    

    Here’s a sample return

           URL: http://test-install.blindsidenetworks.com/bigbluebutton/
        Secret: 8cd8ef52e8e101574e400365b55e11a6
    

    You should not embed the shared secret witin a web page and make BigBlueButton API calls within JavaScript running within a browser. An end user will be able to see the shared secret within in their browser (the built-in debugging tools would make this secret easily accessibile). Once someone has the shared secret for your BigBlueButton server, they could create their own API calls. If the shared secret stays on the server components of your application, then it’s never visible to end-users.

    Configuration

    The shared secret is set in

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

    Look for the parameter (it’s called securitySalt due to legacy naming of the string)

       securitySalt=<your_salt>
    

    When you install BigBlueButton, the packaging scripts create a random 32 character shared secret. You can also change the secret at anytime using the command bbb-conf.

       bbb-conf --setsecret <new_shared_secret>
    

    IMPORTANT: DO NOT ALLOW END USERS TO KNOW YOUR SHARED SECRET OR ELSE YOUR SECURITY WILL BE COMPROMISED.

    Usage

    The implementation of this security model lies in ApiController.groovy. It entails creating a checksum out of the combination of the entire HTTP query string and a server-configured security token.

    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 + salt)
    • PHP
      • simply call sha(string + salt)

    Error handling

    All API calls make a best-effort attempt to return a properly formatted document that contains enough information for the user to be able to determine what the error is.

    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

    API Calls

    The following response parameters are standard to every call and may be returned from any call.

    Parameters:

    Param NameRequired / OptionalTypeDescription
    checksum Varies String

    See the Security section for more details on the usage for this parameter.

    This is basically a SHA-1 hash of callName + queryString + securitySalt. The security salt will be configured into the application at deploy time. All calls to the API must include the checksum parameter.

    Response:

    Param NameWhen ReturnedTypeDescription
    returncodeAlwaysString

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

    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.

    messageKeySometimesString

    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, your application can always call create before returning the join URL. This way, regardless of the order in which users join, the meeting will always exist but won’t be empty. The BigBlueButton server will automatically remove empty meetings that were created but have never had any users after a number of minutes specified by defaultMeetingCreateJoinDurationdefined in bigbluebutton.properties.

    Resource URL:

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

    Parameters:

    Param NameRequired / OptionalTypeDescription
    nameOptionalString A name for the meeting.
    meetingIDRequiredString

    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, this all but guarantees that different meetings will not have the same meetingID.

    attendeePWRequiredString The password that will be required for attendees to join the meeting. This is optional, and if not supplied, BigBlueButton will assign a random password.
    moderatorPWRequiredString

    The password that will be required for moderators to join the meeting or for certain administrative actions (i.e. ending a meeting). This is optional, and if not supplied, BigBlueButton will assign a random password (which will be returned in the create response).

    welcomeOptionalString

    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.

    You can set a default welcome message on 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.

    dialNumberOptionalString

    The dial access number that participants can call in using regular phone. You can set a default dial number on bigbluebutton.properties

    voiceBridgeOptionalString

    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.

    webVoiceOptionalString

    Voice conference alphanumeric that participants enter to join the voice conference.

    Using this parameter requires custom configuration of the FreeSWITCH server.

    logoutURLOptionalString

    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.loggedOutURL from bigbluebutton.properties

    recordOptionalBoolean

    Setting ‘record=true’ instructs the BigBlueButton server to record the media and events in the session for later playback. The default is false.

    When using BigBlueButton 1.0 or later, in order for a recording to be generated, a section of the live meeting must be selected using the Recording UI control in BigBlueButton. See also the autoStartRecording and allowStartStopRecording parameters.

    durationOptionalNumber

    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 (same as receiving an end API request).

    metaOptionalString

    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.

    The parameter name is generated by using the prefix meta_ followed by a custom metadata key. The metadata key should contain only ASCII letters, digits, and the characters - and _. It cannot start with -. You can use uppercase or lowercase characters in metadata keys, but they will all be converted to lowercase when received by BigBlueButton.

    Examples of the use of the meta paramters are meta_Presenter=Jane%20Doe, meta_category=FINANCE, meta_TERM=Fall2016, etc.

    moderatorOnlyMessageOptionalString

    Display a message to all moderators in the public chat.

    The value is interpreted in the same way as the welcome parameter.

    autoStartRecordingOptionalBoolean

    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.

    NOTE: Don’t set to autoStartRecording=false and allowStartStopRecording=false - the moderator won’t be able to start recording!

    allowStartStopRecordingOptionalBoolean

    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.

    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>
      <meeting>
        <meetingID>Test</meetingID>
        <createTime>1308591802</createTime>
        <attendeePW>ap</attendeePW>
        <moderatorPW>mp</moderatorPW>
        <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
        <messageKey>createSuccess</messageKey>
        <message>Meeting has been create</message>
      </meeting>
    </response>
    

    Preupload Slides

    You can now preupload slides within the create call. You can specify an URL for BigBlueButton to download and process the slides, or you can embed the slides in base64 as part of the POST request. For use the preupload slides part, you have to send a HTTP 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.samplepdf.com/sample.pdf" />
              <document name="sample-presentation.pdf">JVBERi0xLjQKJ....
                [clipped here]
                ....0CiUlRU9GCg==
              </document>
           </module>
        </modules>
    

    For more information about the preupload slides check the following link. For a complete example of the preupload slides check the following demos: demo7 and demo8

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

    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 no XML response for this call if it is properly formatted. You should simply redirect the user to the call URL, and they will be entered into the meeting.

    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 Required 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-1411067830029
      </internalMeetingID>
      <createTime>1411067830029</createTime>
      <createDate>Thu Sep 18 19:17:10 UTC 2014</createDate>
      <voiceBridge>74518</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>1411067830152</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>r4osda8xzlsg</userID>
          <fullName>stu</fullName>
          <role>VIEWER</role>
          <isPresenter>false</isPresenter>   
          <isListeningOnly>false</isListeningOnly>   
          <hasJoinedVoice>true</hasJoinedVoice>   
          <hasVideo>true</hasVideo>   
          <customdata/>
        </attendee>
        <attendee>
          <userID>jgkgwilgigcf</userID>
          <fullName>mod</fullName>
          <role>MODERATOR</role>
          <isPresenter>true</isPresenter>   
          <isListeningOnly>true</isListeningOnly>   
          <hasJoinedVoice>false</hasJoinedVoice>   
          <hasVideo>false</hasVideo>   
          <customdata/>
        </attendee>
      </attendees>
      <metadata/>
      <messageKey/>
      <message/>
    </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:

    Now, In BigBlueButton 0.80 is not 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>
          <meetingID>Demo Meeting</meetingID>
          <meetingName>Demo Meeting</meetingName>
          <createTime>1411067830029</createTime>
          <createDate>Thu Sep 18 19:17:10 UTC 2014</createDate>
          <voiceBridge>74518</voiceBridge>   
          <dialNumber>613-555-1234</dialNumber>   
          <attendeePW>ap</attendeePW>
          <moderatorPW>mp</moderatorPW>
          <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
          <running>true</running>
          <participantCount>2</participantCount>   
          <listenerCount>1</listenerCount>   
          <voiceParticipantCount>1</voiceParticipantCount>   
          <videoCount>1</videoCount>   
          <duration>0</duration>
          <hasUserJoined>true</hasUserJoined>
        </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:

        <response>
          <returncode>SUCCESS</returncode>
          <recordings>
            <recording>
               <recordID>183f0bf3a0982a127bdb8161-1308597520</recordID>
               <meetingID>CS101</meetingID>
               <name><![CDATA[On-line session for CS 101]]></name>
               <published>false</published>
               <state>unpublished</state>
               <startTime>34545465656</startTime>
               <endTime>34575565465</endTime>
               <metadata>
                  <title><![CDATA[Test Recording]]></title>
                  <subject><![CDATA[English 232 session]]></subject>
                  <description><![CDATA[First Class]]></description>
                  <creator><![CDATA[Fred Dixon]]></creator>
                  <contributor><![CDATA[Richard Alam]]></contributor>
                  <language><![CDATA[en_US]]></language>
               </metadata>
               <playback>
                  <format>
                     <type>presentation</type>
                     <url>http://server.com/presentation/playback?recordID=183f0bf3a0982a127bdb8161-1...</url>
                     <length>62</length>
                  </format>
               </playback>
            </recording>
            <recording>
               <recordID>183f0bf3a0982a127bdb8161-13085974450</recordID>
               <meetingID>CS102</meetingID>
               ...
            </recording>
          </recordings>
          <messageKey/>
          <message/>
        </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>
    

    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>
    

    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 work underway ot create a 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 againt a local BigBlueButton server.

    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.