BBB XML Api

BigBlueButton API Documentation
Table of Contents
Overview ........................................................................................................................... 1
Overall API Usage ............................................................................................................... 2
Create meeting (with your own meeting ID) eam!le" ......................................................... 2
Create meeting (with no meeting ID) eam!le" .................................................................. 2
#oin meeting eam!le" .................................................................................................... 2
Is meeting running eam!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
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 eam!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!f75ee!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>
<meetingToken>0752*56f-dca-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(
<response>
<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 eam!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 maimum atten&ees) to mo&i(y the meeting that is .eing
create& .y the thir& !arty a!!.
;hose eam!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 wthout the chec/sum !arameter.
(eam!le (or create meeting API call"
nameA;estB%eetingCmeetingIDAa.c12'Catten&eePDA111222Cmo&eratorPDA'''**
*)
2. A!!en& the security salt to your string
eam!le (or a.ove >uery string"
security salt is 2'6206&*76&&47*.207.(81760(6023ea(*.
$tring .ecomes"
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&& a chec/sum !arameter to your >uery string that contains this chec/sum.
A.ove eam!le .ecomes"
nameA;estB%eetingCmeetingIDAa.c12'Catten&eePDA111222Cmo&eratorPDA'''**
*Cchec/sumA(e1('(8'2&*28663a0aa2(&a&.21e.a'*2a462a&
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 eist in nearly all !rogramming languages. =ere are
eam!le metho&s or lin/s to eam!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 eists 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&
!rocess the returne& ?%9 (using 5Juery an& $.xml!son< (or eam!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 eam!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 #e,uired -
Optional
Type Description
chec/sum Karies $tring $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.
!es"onse
"aram $ame &hen
#eturned
Type Description
returnCo&e Always $tring 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&.
message $ometimes $tring 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.
messageLey $ometimes $tring 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.
#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
Parameters
Optional
Type Description
name 1e>uire& $tring 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.
atten&eePD O!tional $tring ;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&.
mo&eratorPD O!tional $tring ;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&.
maPartici!ants O!tional MM ,um.er ;he maimum 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.
Author: Jeremy Thomerson Page * of 11 09/21/09 04:59:03 PM
Optional
Type Description
meetme$erver O!tional MM $tring ;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 &hen
#eturned
Type Description
meeting;o/en Always $tring ;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.
meetingID $ometimes $tring ;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.
atten&eePD Always $tring ;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&.
mo&eratorPD Always $tring ;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&.
Author: Jeremy Thomerson Page + of 11 09/21/09 04:59:03 PM
%oin meeting #&oin$
Parameters
Optional
Type Description
(ull,ame 1e>uire& $tring ;he (ull name that is to .e use& to i&enti(y this
user to other con(erence atten&ees.
meeting;o/en O!tional $tring ;he internal meeting to/en assigne& .y the API
(or this meeting when it was create&. ,ote that
ether 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&.
meetingID O!tional $tring I( you s!eci(ie& a meeting ID when calling create<
then you can use ether the generate& meeting
to/en or your s!eci(ie& meeting ID to (in&
meetings. ;his !arameter ta/es your meeting ID.
!asswor& O!tional $tring ;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)
re&irectImme&ia
tely
O!tional Boolean 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.
!es"onse
"aram $ame &hen
#eturned
Type Description
entryU19 Always $tring ;he U19 that the user can .e sent to in or&er to
5oin the meeting. Dhen they go to this U19< BBB
will setu! their client session an& re&irect them
into 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.
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
Optional
Type Description
(or this meeting when it was create&.
!es"onse
"aram $ame &hen
#eturned
Type Description
running Always $tring 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
Optional
Type Description
(or this meeting when it was create&. ,ote that
ether 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&.
!asswor& 1e>uire& $tring ;he mo&erator !asswor& (or this meeting. Eou
can not en& a meeting using the atten&ee
!asswor&.
!es"onse
"aram $ame &hen
#eturned
Type Description
en&e& Always $tring 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.
)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.

BBB XML Api

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

BBB XML Api

Enviado por

Direitos autorais:

Formatos disponíveis

BigBlueButton API Documentation

Você também pode gostar