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:

Fixed Issue 487 - Add the action name to the checksum calculation.
Fixed Issue 473 - Remove "meetingToken" from the API.
Fixed Issue 394 - Need endMeeting API call implemented.
Fixed Issue 247 - DynamicConferenceService never cleans out ended conferences.
Fixed 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 and voiceBridge

For a detail of the updates in the api 0.8 check the following 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.

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

Create the entire query string for your API call without the checksum parameter.

Example for create meeting API call: "name=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444"

Prepend the call name to your string

Example for above query string:

call name is "create"
String becomes: "createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444"

Now, append the security salt to your string

Example for above query string:

security salt is "639259d4-9dd8-4b25-bf01-95f9567eaf4b"
String becomes: "createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444639259d4-9dd8-4b25-bf01-95f9567eaf4b"

Now, find the SHA-1 sum for that string (implementation varies based on programming language).

he SHA-1 sum for the above string is: "1fcbb0c4fc1f039f73aa6d697d2db9ba7f803f17"

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"

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:

JavaScript (describes MD5 also): http://pajhome.org.uk/crypt/md5/
Java: http://commons.apache.org/codec/

You can use org.apache.commons.codec.digest.DigestUtilsandcall DigestUtils.shaHex(string + salt)

PHP: simply call sha(string + salt)

See http://php.net/manual/en/function.sha1.php

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

In the following section is described the administration calls

Resource	Description
create	Creates a new meeting.
join	Join a new user to an existing meeting.
end	Ends meeting.

Monitoring

In the following section is described the monitoring calls

Resource	Description
isMeetingRunning	Checks whether if an specified meeting is running.
getMeetings	Get a list of the Meetings.
getMeetingInfo	Get the details of a Meeting.

Recording

Resource	Description
getRecordings	Get a list of recordings.
publishRecordings	Enables to publish or unpublish a recording.
deleteRecordings	Deletes a existing Recording

API Calls

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.

Standard parameters and responses

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

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 Meeting

Creates a bigbluebutton meeting, according to the parameters passed.

Resource URL:

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

Parameters:

Param Name	Required / Optional	Type	Description
name	Required	String	A name for the meeting.
meetingID	Required	String	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.
attendeePW	Optional	String	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.
moderatorPW	Optional	String	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.
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. You can set a default welcome message on bigbluebutton.properties
dialNumber	Optional	String	The dial access number that participants can call in using regular phone. You can set a default dial number on 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, 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.
webVoice	Optional	String	Voice conference alphanumberic that participants enter to join the voice conference.
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.loggedOutURL` if defined in bigbluebutton.properties .
maxParticipants	Optional (NFS)	Number	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.
record	Optional	String	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.
duration	Optional	Number	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.
meta	Optional	String	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:

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

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 Meeting

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

Example Requests:

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.

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:

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 Meeting

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.

TODO: In future iterations, this call will also mark a meeting that has ended so that it can not be immediately restarted with the same join meeting URLs that initially dropped users into the meeting. This will protect against devious users restarting a meeting that you just kicked them from.

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:

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>Test</meetingName>
   <meetingID>test01</meetingID>
   <createTime>1315254777880</createTime>
   <voiceBridge>70775</voiceBridge>
   <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]

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]

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.

Example Requests:

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]

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 meetingIDs separate by commas.
publish	Required	String	The value for publish or unpublish the recording(s). Available values: true or false.

Example Requests:

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]

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 meetingIDs separate by commas.

Example Requests:

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

PHP

Needs to be updated, however you can find it useful: 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

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

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

you can check the code in: 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

The code for the extension can be found at: 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.

We are already announcing events such as this within BBB 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.