BigBlueButton API Documentation

Table of Contents
Overview...........................................................................................................................1 Overall API Usage...............................................................................................................2 Create meeting (with your own meeting ID) e am!le".........................................................2 Create meeting (with no meeting ID) e am!le"..................................................................2 #oin meeting e am!le"....................................................................................................2 Is meeting running e am!le"............................................................................................2 API $ecurity %o&el..............................................................................................................' Con(iguration..................................................................................................................' Usage............................................................................................................................' )rror han&ling................................................................................................................* Desire& +uture +eatures.......................................................................................................* $u!!ort (or #$O, - #$O,P................................................................................................* %eeting event call.ac/s...................................................................................................0 API Calls............................................................................................................................0 $tan&ar& !arameters an& res!onses..................................................................................0 Parameters"...........................................................................................................0 1es!onse"..............................................................................................................2 %eeting wor/(low calls.....................................................................................................2 Create meeting (create)...............................................................................................2 Parameters"...........................................................................................................3 1es!onse"..............................................................................................................4 #oin meeting (5oin)......................................................................................................6 Parameters"...........................................................................................................6 1es!onse"..............................................................................................................6 Bac/7o((ice a&ministration calls.........................................................................................6 Is meeting running (is%eeting1unning)........................................................................18 Parameters"..........................................................................................................18 1es!onse"............................................................................................................18 )n& %eeting (en&%eeting)..........................................................................................18 Parameters"..........................................................................................................18 1es!onse"............................................................................................................11 9ist %eeting Atten&ees (listAtten&ees).........................................................................11 :et %eeting In(o (get%eetingIn(o)...............................................................................11

Overview
;his &ocument outlines the API that is availa.le (or integrating BigBlueButton with other a!!lications. It is currently in &ra(t stage as not all (eatures are availa.le. +eatures which are not currently im!lemente& will .e clearly mar/e& as such.

Author: Jeremy Thomerson

Page 1 of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

Overall API Usage

;he API is im!lemente& with the en&7user in min&. ;o call the API< you sim!ly ma/e an =;;P re>uest to a U19 with the >uery !arameters su!!lying the in(ormation nee&e& (or the call. ;he API returns an ?%9 res!onse. =ere are some e am!le API calls an& their res!onses"

Create meeting (with your own meeting ID) example:

htt!"--yourserver.com-.ig.lue.utton-a!i-create@ nameA;estB%eetingCmeetingIDAa.c&e(Catten&eePDA111222Cmo&eratorPDA'''***
<response> <returncode>SUCCESS</returncode> <meetingToken>6db0a605-627f- f6c-a!" -5!f7 5ee!72c</meetingToken> <meeting#$>abcdef</meeting#$> <attendee%&>'''222</attendee%&> <moderator%&>!!! </moderator%&> <message(e)/> <message/> </response>

Create meeting (with no meeting ID) example:

htt!"--yourserver.com-.ig.lue.utton-a!i-create@nameA;estB%eetingCmeetingIDA(e&c.a
<response> <returncode>SUCCESS</returncode> <meetingToken>0752*56f-dc a- 6f'-"'a7-a'f*"0' c72!</meetingToken> <meeting#$>fedcba</meeting#$> <attendee%&>t+er,pa)</attendee%&> <moderator%&>e-ma" ,p</moderator%&> <message(e)/> <message/> </response>

Join meeting example:

htt!"--yourserver.com-.ig.lue.utton-a!i-5oin@ (ull,ameA#oeBUserCmeetingIDAa.c&e(C!asswor&A'''*** ;his call sen&s the caller &irectly into the a!!lication. ;here is no ?%9 res!onse. Eou shoul& re&irect your user to a U19 li/e this when you are &one creating the meeting an& are rea&y to &irect them into the meeting.

Is meeting running example:

htt!"--yourserver.com-.ig.lue.utton-a!i-is%eeting1unning@meetingIDAa.c&e(

Author: Jeremy Thomerson

Page 2 of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

<response> <returncode>SUCCESS</returncode> <running>true</running> </response>

%ore &etails on these calls can .e (oun& in the FAPI CallsG section .elow.

API Security Model

;he API !rovi&es a way to .e secure& so that thir&7!arty a!!s may ma/e calls to it< .ut not allow other !eo!le (en& users) to ma/e similar calls to create their own meetings< etc. +or instance< a thir& !arty a!!lication that is integrate& with the API may em.e& a #ava$cri!t U19 that calls to the BBB API to create a meeting. An en& user will .e a.le to see this U19 in their .rowser an& shoul& not .e allowe& to mo&i(y a !arameter ((or e am!le< the meeting ID) an& create their own meeting. By &oing so< they coul& create meetings that were not trac/e& .y the thir&7!arty a!!< which coul& !resent a .illing !ro.lem< et cetera. ;hey shoul& also not .e a.le to mo&i(y any !arameter ((or instance the ma imum atten&ees) to mo&i(y the meeting that is .eing create& .y the thir& !arty a!!. ;hose e am!les are clearly a.uses o( the system< an& there(ore must .e !rotecte& against. ;he API must !rovi&e a way o( ena.ling this !rotection.

Configuration
TODO: the securitySalt is currently set on the ApiController and needs to be able to be configured via bigbluebutton.properties (or similar) !"O#TA$T: DO $OT A%%O& '$D (S'#S TO )$O& *O(# S'C(# T* SA%T O# '%S' *O(# S'C(# T* & %% +' CO!"#O! S'D.

Usage
;he im!lementation o( this security mo&el lies in A!iController.groovy. It entails creating a chec/sum out o( the com.ination o( the entire =;;P >uery string an& a server7con(igure& security to/en. ;o use the security mo&el< you must .e a.le to create an $=A71 chec/sum out o( the >uery string plus the security salt that you con(igure& on your server. ;o &o so< (ollow these ste!s" 1. Create the entire >uery string (or your API call w thout the chec/sum !arameter. (e am!le (or create meeting API call" nameA;estB%eetingCmeetingIDAa.c12'Catten&eePDA111222Cmo&eratorPDA'''** *) 2. A!!en& the security salt to your string e am!le (or a.ove >uery string" security salt is 2'6206&*76&&47*.207.(81760(6023ea(*. $tring .ecomes"
Author: Jeremy Thomerson Page 3 of 11 09/21/09 04:59:03 PM

BigBlueButton API Documentation

nameA;estB%eetingCmeetingIDAa.c12'Catten&eePDA111222Cmo&eratorPDA''' ***2'6206&*76&&47*.207.(81760(6023ea(*. '. ,ow< (in& the $=A71 sum (or that string (im!lementation varies .ase& on !rogramming language). ;he $=A71 sum (or the a.ove string is" (e1('(8'2&*28663a0aa2(&a&.21e.a'*2a462a& A.ove e am!le .ecomes" nameA;estB%eetingCmeetingIDAa.c12'Catten&eePDA111222Cmo&eratorPDA'''** *Cchec/sumA(e1('(8'2&*28663a0aa2(&a&.21e.a'*2a462a& *. A&& a chec/sum !arameter to your >uery string that contains this chec/sum.

I( you con(igure& a security salt on your server< you MUST sen& this chec/sum with EVERY API call. $ince en& users &o not /now your security salt< they can not (a/e calls to the server< an& they can not mo&i(y your calls H since changing a single !arameter name or value .y only one character will com!letely change the chec/sum re>uire& to vali&ate the call. Im!lementations o( the $=A71 (unctionality e ist in nearly all !rogramming languages. =ere are e am!le metho&s or lin/s to e am!le im!lementations (or various languages" #ava$cri!t (&escri.es %D0 also)" htt!"--!a5home.org.u/-cry!t-m&0#ava" htt!"--commons.a!ache.org-co&ec Eou can use org.apache.commons.codec.digest.DigestUtils an& call DigestUtils.shaHex(string + salt)

P=P" sim!ly call sha(string + salt) See http://php.net/manual/en/function.sha1.php

Error handling
Any invali& API calls shoul& return a !ro!erly (ormatte& &ocument that contains enough in(ormation (or the user to .e a.le to &etermine what the error is. It woul& .e goo& i( this returne& a reasona.le error message as well as a &istinct error /ey (or each ty!e o( error so that en& users coul& internationaliIe their a!!lications an& !rovi&e custom messages .ase& only on the /ey that we return. i.e. 7 an invali& re>uest may return an error message o( F,o con(erence e ists with that to/en IDG .ut the error /ey returne& is sim!ly Finvali&;o/enIDG.

Desired Future Features

Support for JSO

! JSO "

It woul& .e very nice to o!tionally allow #$O, res!onses< an& to su!!ort #$O,P. ;his might allow (or sim!ler integrations< even within static or almost7static we.!ages using #ava$cri!t as the !rimary integration language. It shoul& not .e assume& that all users will .e running custom so(tware on a server an& .e a.le to !rocess ?%9 res!onses< etc. ;his .eing sai&< even within #ava$cri!t there are sim!le ways to ma/e the API call an&

Author: Jeremy Thomerson

Page 4 of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

!rocess the returne& ?%9 (using 5Juery an& $.xml !son< (or e am!le)

#eeting e$ent %all&a%'s

;his may actually even .e calle& a Freverse APIG 7 where we &e(ine an inter(ace that the thir&7 !arty a!!lication can im!lement to .e noti(ie& o( events. ;his woul& not .e necessary (or the (irst version o( the API< .ut woul& .e a nice (eature (or (uture enhancements. %ore &etails" Dhen ma5or events ha!!en within meetings< it woul& .e very hel!(ul to !rovi&e a way (or thir&7!arty a!!lications to .e noti(ie& o( these events. +or instance< when a user 5oins a con(erence< they will !resuma.ly .e 5oining through the thir&7!arty a!!. =owever< when they leave the con(erence< the a!! may have certain au&iting that it nee&s to &o to recor& their &isconnect time< etc. I( BBB coul& ma/e some call.ac/ to the a!!lication< this woul& assist in such scenarios. +or e am!le< the a!!lication may .e a.le to register a U19 that BBB woul& call with status u!&ates. BBB woul& &e(ine an API that such an a!! woul& .e re>uire& to im!lement at that U19. i.e. 7 BBB coul& call" htt!"--thir&7!arty7a!!-...7integ.!h!@eventAuser9e(tCuserIDA12'* htt!"--thir&7!arty7a!!-...7integ.!h!@eventAmeeting)n&e&CmeetingIDAa.c&

De are alrea&y announcing events such as this within BBB through Active%J to communicate .etween the 1e&0 a!!s where these events originate an& the API. It woul& !ro.a.ly not .e very &i((icult to register a&&itional listeners through the $!ring Integration con(iguration that will ma/e these =;;P calls (or us (or each event.

API Calls
Standard parameters and responses
;he (ollowing res!onse !arameters are stan&ar& to every call an& may .e returne& (rom any call.

Parameters
"aram $ame chec/sum #e,uired Optional Karies Type $tring Description $ee the F$ecurityG section (or more &etails on the usage (or this !arameter. ;his is .asically an $=A71 hash o( >uery$tring B security$alt. ;he security salt will .e con(igure& into the a!!lication at &e!loy time. I( a security salt is !resent< all calls to the API must inclu&e the chec/sum !arameter.

Author: Jeremy Thomerson

Page 5 of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

!es"onse
"aram $ame returnCo&e &hen #eturned Always Type $tring Description In&icates whether the inten&e& (unction was success(ul or not. Always one o( two values" !A"#$% H there was an error o( some sort H loo/ (or the message an& messageLey (or more in(ormation. ,ote that i( the returnCo&e is +AI9)D< the call7s!eci(ic res!onse !arameters mar/e& as Falways returne&G will not .e returne&. ;hey are only returne& as !art o( success(ul res!onses. &'(($&& H the call succee&e& H the other !arameters that are normally associate& with this call will .e returne&. A message that gives a&&itional in(ormation a.out the status o( the call. A message !arameter will always .e returne& i( the returnCo&e was +AI9)D. A message may also .e returne& in some cases where returnCo&e was $UCC)$$ i( a&&itional in(ormation woul& .e hel!(ul. Provi&es similar (unctionality to the message an& (ollows the same rules. =owever< a message /ey will .e much shorter an& will generally remain the same (or the li(e o( the API whereas a message may change over time. I( your thir& !arty a!!lication woul& li/e to internationaliIe or otherwise change the stan&ar& messages returne&< you can loo/ u! your own custom messages .ase& on this messageLey.

message

$ometimes

$tring

messageLey

$ometimes

$tring

#eeting wor'flow %alls

;hese calls are the !rimary calls o( the API. ;hey are use& (or creating an& 5oining meetings. NOTE: Parameters mar/e& with MM are not yet (ully su!!orte&. Eou can !ass them in to the controller< .ut they may not have any actual e((ect on the con(erence. ;his is more a limitation .ase& on su!!ort .y the actual BBB a!!lication more than the API itsel(.

Create meeting #create$

) am!le U19" htt!"--yourserver.com-.ig.lue.utton-a!i-create@ N!arametersOCchec/sumANchec/sumO

Author: Jeremy Thomerson

Page ) of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

Parameters
"aram $ame name #e,uired Optional 1e>uire& Type $tring Description A name (or the meeting. TODO: Currently there is no .ay to specify a name for the meeting that is different than the meeting D - meetme room name. This is a limitation of +++ client and not really the A" . meetingID O!tional $tring A meeting ID that can .e use& to i&enti(y this meeting .y the thir& !arty a!!lication. ;his is o!tional< an& i( not su!!lie&< BBB will generate a meeting to/en that can .e use& to i&enti(y the meeting. ;he !asswor& that will .e re>uire& (or atten&ees to 5oin the meeting. ;his is o!tional< an& i( not su!!lie&< BBB will assign a ran&om !asswor&. ;he !asswor& that will .e re>uire& (or mo&erators to 5oin the meeting or (or certain a&ministrative actions (i.e. en&ing a meeting). ;his is o!tional< an& i( not su!!lie&< BBB will assign a ran&om !asswor&. ;he ma imum num.er o( !artici!ants to allow into the meeting (inclu&ing mo&erators). A(ter this num.er o( !artici!ants have 5oine&< BBB will return an a!!ro!riate error (or other users trying to 5oin the meeting. A negative num.er in&icates that an unlimite& num.er o( !artici!ants shoul& .e allowe& (this is the &e(ault setting). TODO: This can be supplied to the A" currently/ but +++ does not actually restrict access yet once the room is full. meetme1oom O!tional MM $tring ;he name o( the meetme room to use (or au&io con(erencing.

atten&eePD

O!tional

$tring

mo&eratorPD

O!tional

$tring

ma Partici!ants

O!tional MM

,um.er

Author: Jeremy Thomerson

Page * of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation

"aram $ame meetme$erver #e,uired Optional O!tional MM Type $tring Description ;he name o( the server that will .e han&ling the au&io !ortion o( this con(erence. TODO: This is not currently supported by +++ at all. t .ould be very nice to allo. this to be configurable and not assume that the Asteris0 and +++ servers .ill have a 1:1 relationship. 2or e3ample/ some applications assign the .eb and audio portions to independent servers based on current load at the time of meeting creation. &ebServerA might have t.o +++ conferences on it/ .hile "honeServerA and "honeServer+ are handling the actual Asteris0 portion of each of those meetings.

!es"onse
"aram $ame meeting;o/en &hen #eturned Always Type $tring Description ;he internal meeting to/en assigne& .y the API (or this meeting. It can .e use& .y su.se>uent calls (or 5oining or otherwise mo&i(ying a meetingPs status. ;he meeting ID su!!lie& .y the thir& !arty a!!< or null i( none was su!!lie&. I( can .e use& in con5unction with a !asswor& in su.se>uent calls (or 5oining or otherwise mo&i(ying a meetingPs status. ;he !asswor& that will .e re>uire& (or atten&ees to 5oin the meeting. I( you &i& not su!!ly one< BBB will assign a ran&om !asswor&. ;he !asswor& that will .e re>uire& (or mo&erators to 5oin the meeting or (or certain a&ministrative actions (i.e. en&ing a meeting). I( you &i& not su!!ly one< BBB will assign a ran&om !asswor&.

meetingID

$ometimes

$tring

atten&eePD

Always

$tring

mo&eratorPD

Always

$tring

Author: Jeremy Thomerson

Page + of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation %oin meeting #&oin$

Parameters
"aram $ame (ull,ame meeting;o/en #e,uired Optional 1e>uire& O!tional Type $tring $tring Description ;he (ull name that is to .e use& to i&enti(y this user to other con(erence atten&ees. ;he internal meeting to/en assigne& .y the API (or this meeting when it was create&. ,ote that e ther the meeting;o/en or the meetingID along with one o( the !asswor&s must .e !asse& into this call in or&er to &etermine which meeting to (in&. I( you s!eci(ie& a meeting ID when calling create< then you can use e ther the generate& meeting to/en or your s!eci(ie& meeting ID to (in& meetings. ;his !arameter ta/es your meeting ID. ;he !asswor& that this atten&ee is using. I( the mo&erator !asswor& is su!!lie&< he will .e given mo&erator status (an& the same (or atten&ee !asswor&< etc) I( this is !asse& as true< then BBB will not return a U19 (or you to re&irect the user to< .ut will instea& treat this as an entry U19 an& will imme&iately set u! the client session an& re&irect the user into the con(erence. Kalues can .e either a 1 (one) or a 8 (Iero)< in&icating true or (alse res!ectively. De(aults to (alse.

meetingID

O!tional

$tring

!asswor&

O!tional

$tring

re&irectImme&ia tely

O!tional

Boolean

!es"onse
"aram $ame entryU19 &hen #eturned Always Type $tring ;he 5oin will into Description U19 that the user can .e sent to in or&er to the meeting. Dhen they go to this U19< BBB setu! their client session an& re&irect them the con(erence.

(a%')offi%e administration %alls

;hese calls may .e use& .y the .ac/7o((ice a!!lications to han&le meeting management< etc.

Author: Jeremy Thomerson

Page 9 of 11

09/21/09 04:59:03 PM

BigBlueButton API Documentation Is meeting running #isMeeting!unning$

;his call ena.les you to sim!ly chec/ on whether or not a meeting is running .y loo/ing it u! with either the to/en or your ID.

Parameters
"aram $ame meeting;o/en meetingID #e,uired Optional O!tional O!tional Type $tring $tring Description ;he internal meeting to/en assigne& .y the API (or this meeting when it was create&. I( you s!eci(ie& a meeting ID when calling create< then you can use e ther the generate& meeting to/en or your s!eci(ie& meeting ID to (in& meetings. ;his !arameter ta/es your meeting ID.

!es"onse
"aram $ame running &hen #eturned Always Type $tring Description A string o( either FtrueG or F(alseG that signals whether a meeting with this ID or to/en is currently running.

'nd Meeting #endMeeting$

Use this to (orci.ly en& a meeting an& /ic/ all !artici!ants out o( the meeting. TODO: this call is not yet implemented.

Parameters
"aram $ame meeting;o/en #e,uired Optional O!tional Type $tring Description ;he internal meeting to/en assigne& .y the API (or this meeting when it was create&. ,ote that e ther the meeting;o/en or the meetingID along with one o( the !asswor&s must .e !asse& into this call in or&er to &etermine which meeting to (in&. I( you s!eci(ie& a meeting ID when calling create< then you can use e ther the generate& meeting to/en or your s!eci(ie& meeting ID to (in& meetings. ;his !arameter ta/es your meeting ID. ;he mo&erator !asswor& (or this meeting. Eou can not en& a meeting using the atten&ee !asswor&.
09/21/09 04:59:03 PM

meetingID

O!tional

$tring

!asswor&

1e>uire&

$tring

Author: Jeremy Thomerson

Page 10 of 11

BigBlueButton API Documentation

!es"onse
"aram $ame en&e& &hen #eturned Always Type $tring Description A string o( either FtrueG or F(alseG that signals whether the meeting was success(ully en&e&.

(ist Meeting Attendees #listAttendees$

;his call will list all current atten&ees o( a meeting. TODO: this call is not yet implemented.

)et Meeting Info #getMeetingInfo$

;his call will return all o( a meetingPs in(ormation< inclu&ing the list o( atten&ees as well as start an& en& times. TODO: this call is not yet implemented.

Author: Jeremy Thomerson

Page 11 of 11

09/21/09 04:59:03 PM