Overview

This document outlines the API that is available for integrating BigBlueButton with other applications. The changes between releases will be described in the document. Features which are not currently implemented will be clearly marked as such.

The API is implemented with the end-user in mind. To call the API, you simply make an HTTP request to a URL with the query parameters supplying the information needed for the call. The API returns an XML response.

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

API Changes in Releases

Version 0.64

Added new API calls: * isMeetingRunning * end * getMeetingInfo * getMeetings

Version 0.7

In 0.70, we made a couple of changes that will force you to update your API integrations. These changes were necessary to improve the security of the API and our ability to add features in future releases. We apologize for any inconvenience this may have caused.

Added new API calls: * api version returned on index

Fixes: * Fixedhttp://code.google.com/p/bigbluebutton/issues/detail?id=487'>https://code.google.com/p/bigbluebutton/issues/detail?id=487'>Issue 487 - Add the action name to the checksum calculation. * Fixed http://code.google.com/p/bigbluebutton/issues/detail?id=473'>https://code.google.com/p/bigbluebutton/issues/detail?id=473'>Issue 473 - Remove "meetingToken" from the API. * Fixed http://code.google.com/p/bigbluebutton/issues/detail?id=394'>https://code.google.com/p/bigbluebutton/issues/detail?id=394'>Issue 394 - Need endMeeting API call implemented. * Fixed http://code.google.com/p/bigbluebutton/issues/detail?id=247'>https://code.google.com/p/bigbluebutton/issues/detail?id=247'>Issue 247 - DynamicConferenceService never cleans out ended conferences. * Fixed http://code.google.com/p/bigbluebutton/issues/detail?id=393'>https://code.google.com/p/bigbluebutton/issues/detail?id=393'>Issue 393 - Need getMeetingInfo API call implemented.

Version 0.8

Added new API calls: * getRecordings * publishRecordings * deleteRecordings

Updates: * create - Now supports pre-uploading slides * create - Added new parameters duration and record * join - Added createTime parameter * getMeetingInfo - Added recording indicator to the response

For a detail of the updates in the api 0.8 check the following http://groups.google.com/group/bigbluebutton-dev/browse_thread/thread/c214cbe9bdb2268a'>link

Version Master Branch

No changes yet.

API Security Model

The API provides a way to be secured so that third-party apps may make calls to it, but not allow other people (end users) to make similar calls to create their own meetings, etc. For instance, a third party application that is integrated with the API may embed a JavaScript URL that calls to the BBB API to create a meeting. An end user will be able to see this URL in their browser and should not be allowed to modify a parameter (for example, the meeting ID) and create their own meeting. By doing so, they could create meetings that were not tracked by the third-party app, which could present a billing problem, etcetera. They should also not be able to modify any parameter (for instance the maximum attendees) to modify the meeting that is being created by the third party app. Those examples are clearly abuses of the system, and therefore must be protected against. The API must provide a way of enabling this protection.

Configuration

The securitySalt is set in

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

Look for the parameter

beans.dynamicConferenceService.securitySalt=<your_salt>

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

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 security salt that you configured on your server. To do so, follow these steps:

If you configured a security salt on your server, you MUST send this checksum with EVERY API call. Since end users do not know your security salt, they can not fake calls to the server, and they can not modify your 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:

NOTE: Parameters marked with (NFS) are not yet fully supported. You can pass them in to the controller, but they may not have any actual effect on the conference. This is more a limitation based on support by the actual BBB application more than the API itself.

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

Parameters:

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

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

Response:

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.

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.

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 Meeting

Creates a bigbluebutton meeting, according to the parameters passed.

Resource URL:

Parameters:

A name for the meeting.

A meeting ID that can be used to identify this meeting by the third party application. This must be unique to the server that you are calling. If you supply a non-unique meeting ID, you will still have a successful call, but will receive a warning message in the response. If you intend to use the recording feature, the meetingID shouldn't contain commas.

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

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, BBB will assign a random password.

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 dial access number that participants can call in using regular phone. You can set a default dial number on bigbluebutton.properties

Voice conference number that participants enter to join the voice conference. The default pattern for this is a 5-digit number, because in the default Asterisk configuration, 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 /etc/asterisk/bbb_extensions.conf. When using the default setup, we recommend you always pass a 5 digit voiceBridge parameter -- and have it begin with the digit '7' if you are using the default FreeSWITCH setup (see FAQ entry). Finally, if you don't pass a value for voiceBridge, then users will not be able to join a voice conference for the session.

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

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 if defined in bigbluebutton.properties

.

The maximum number of participants to allow into the meeting (including moderators). After this number of participants have joined, BBB will return an appropriate error for other users trying to join the meeting. A negative number indicates that an unlimited number of participants should be allowed (this is the default setting).

TODO: This can be supplied to the API currently, but BBB does not actually restrict access yet once the room is full.

Setting ‘record=true’ instructs the BigBlueButton server to record the media and events in the session for later playback. Available values are true or false. Default value is false.

The duration parameter allows to specify the number of minutes for the meeting's length. When the length of the meeting reaches the duration, BigBlueButton automatically ends the meeting. The default is 0, which means the meeting continues until the last person leaves or an end API calls is made with the associated meetingID.

You can pass one or more metadata values for create a meeting. These will be stored by BigBlueButton and later retrievable via the getMeetingInfo call and getRecordings. Examples of meta parameters are meta_Presenter, meta_category, meta_LABEL, etc. All parameters are converted to lower case, so meta_Presenter would be the same as meta_PRESENTER.

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 have to send a HTTP POST request.
  
• The URL Resource has to be the same as the previously described.
  
• In the body part, you would append a simple XML like the following with the presentation to upload:
  

  <?xml version="1.0" encoding="UTF-8"?> 
  
  <modules> 
  
      <module name="presentation"> 
  
          <document url="http://www.samplepdf.com/sample.pdf" /> 
  
          <document name="sample-presentation.pdf">JVBERi0xLjQKJ....
  
            [clipped here]
  
            ....0CiUlRU9GCg==
  
          </document> 
  
      </module> 
  
  </modules> 
  
  

Join Meeting

Joins automatically a user to the meeting specified in the meetingID parameter.

Resource URL:

Parameters:

The full name that is to be used to identify this user to other conference attendees.

The meeting ID that identifies the meeting you are attempting to join.

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)

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.

NEW in 0.7

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

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.

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:

NOTE: there is the possibility that a user is sent to a join URL that is invalid right now. For instance, if the client application forms the URL incorrectly, or sends the user to join a meeting that hasn't been created, then the user will end up seeing the XML that would be returned as an error. We need to figure out a better way of handling this.

Is Meeting Running

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:

Parameters:

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 Meeting

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

Resource URL:

Parameters:

The meeting ID that identifies the meeting you are attempting to end.

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>

Get Meeting Info

This call will return all of a meeting's information, including the list of attendees as well as start and end times.

Resource URL:

Parameters:

The meeting ID that identifies the meeting you are attempting to check on.

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>Test</meetingName>

   <meetingID>test01</meetingID>

   <createTime>1315254777880</createTime>

   <attendeePW>ap</attendeePW>

   <moderatorPW>mp</moderatorPW>

   <running>true</running>

   <recording>false</recording>

   <hasBeenForciblyEnded>false</hasBeenForciblyEnded>

   <startTime>1315254785069</startTime>

   <endTime>0</endTime>

   <participantCount>1</participantCount>

   <maxUsers>20</maxUsers>

   <moderatorCount>1</moderatorCount>

   <attendees>

      <attendee>

         <userID>1</userID>

         <fullName>John Doe</fullName>

         <role>MODERATOR</role>

      </attendee>

   </attendees>

   <metadata/>

   <messageKey/>

   <message/>

</response>

TODO: add participant join / disconnect times to each attendee node.

Get Meetings

This call will return a list of all the meetings found on this server.

Resource URL:

http://yourserver.com/bigbluebutton/api/getMeetings?checksum=[checksum'>http://yourserver.com/bigbluebutton/api/getMeetings?checksum=[checksum]

Parameters:

Now, In BigBlueButton 0.8 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>test01</meetingID>

         <meetingName>Test</meetingName>

         <createTime>1315254777880</createTime>

         <attendeePW>ap</attendeePW>

         <moderatorPW>mp</moderatorPW>

         <hasBeenForciblyEnded>false</hasBeenForciblyEnded>

         <running>true</running>

      </meeting>

   </meetings>

</response>

Get Recordings

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'>http://yourserver.com/bigbluebutton/api/getRecordings?[parameters]&checksum=[checksum]

Parameters:

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.

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

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> 

         <startTime>Thu Mar 04 14:05:56 UTC 2010</startTime> 

         <endTime>Thu Mar 04 15:01:01 UTC 2010</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>simple</type> 

               <url>http://server.com/simple/playback?recordID=183f0bf3a0982a127bdb8161-1...</url> 

               <length>62</length> 

            </format> 

         </playback>

      </recording> 

      <recording> 

         <recordID>183f0bf3a0982a127bdb8161-13085974450</recordID> 

         <meetingID>CS102</meetingID> 

         ... 

      </recording> 

   </recordings> 

   <messageKey/> 

   <message/> 

</response>

Publish Recordings

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

Resource URL:

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

Parameters:

A record ID for specify the recordings to apply the publish action. It can be a set of meetingIDs separate by commas.

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>

Delete Recordings

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'>http://yourserver.com/bigbluebutton/api/deleteRecordings?[parameters]&checksum=[checksum]

Parameters:

A record ID for specify the recordings to delete. It can be a set of meetingIDs separate 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>

API Sample Code

Overview

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.

Language code

JSP

It is updated with the latest API version: https://github.com/bigbluebutton/bigbluebutton/tree/master/bbb-api-demo'>https://github.com/bigbluebutton/bigbluebutton/tree/master/bbb-api-demo'>https://github.com/bigbluebutton/bigbluebutton/tree/master/bbb-api-demo

PHP

Needs to be updated, however you can find it useful: https://github.com/bigbluebutton/bigbluebutton/tree/master/labs/bbb-api-php'>https://github.com/bigbluebutton/bigbluebutton/tree/master/labs/bbb-api-php

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

Ruby

Needs to be updated, however you can find it useful:
https://github.com/mconf/bigbluebutton-api-ruby'>https://github.com/mconf/bigbluebutton-api-ruby

Javascript

See the Chrome extension that allows for API testing. Obviously implementing your entire integration in JavaScript is risky because you must expose your security salt. This is not recommended. Also note that if you integrate using Javascript and you are calling the API on a different domain than the one that your JavaScript is being served from, you will have cross-site scripting issues. Also, needs to be updated: http://github.com/jthomerson/BigBlueButton-api-chrome-extension'>http://github.com/jthomerson/BigBlueButton-api-chrome-extension

API Testing Tools

If you are developing in bigbluebutton, most of the time you will need to make many API calls. You can use the following tools that will help you for your tests.

BBB API Buddy

This application will help you to automatically generate the most commons URL's of the bigbluebutton API. You just need to fill the fields and test!
http://www.omarshammas.com/bbbapibuddy'>http://www.omarshammas.com/bbbapibuddy

you can check the code in:
https://github.com/omarshammas/bigbluebutton-API-Buddy'>https://github.com/omarshammas/bigbluebutton-API-Buddy

Chrome extension

There is a Chrome extension that allows for quickly testing the API functionality. It's currently working with the 0.7 API. You can also use it to help you understand usage of the API.

The extension can be found at: https://chrome.google.com/extensions/detail/ncbonhmhjnamefpmmjdpbohnkbeliehb'>https://chrome.google.com/extensions/detail/ncbonhmhjnamefpmmjdpbohnkbeliehb

The code for the extension can be found at: http://github.com/jthomerson/BigBlueButton-api-chrome-extension'>http://github.com/jthomerson/BigBlueButton-api-chrome-extension

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 BBB 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 BBB would call with status updates. BBB would define an API that such an app would be required to implement at that URL.
  
  • i.e. -BBB 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 BBB through ActiveMQ 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.