API BigBlueButton

Apercu

L’API BigBlueButton permet aux développeurs de gérer les réunions de visioconférence de manière programmatique. Les fonctionnalités principales incluent la création et la gestion de réunions, la gestion des enregistrements, l’insertion de documents et l’envoi de messages dans le chat.

Tous les appels API nécessitent des requêtes HTTPS vers le endpoint du serveur (généralement /bigbluebutton/api) avec un checksum calculé pour la sécurité.

Types de données

• String : Texte encodé en UTF-8 sans caractères de contrôle (0x00-0x1F). Doit être URL-encodé pour les caractères internationaux.
• Number : Entiers non négatifs (0-9 uniquement), pas de signes ni de ponctuation.
• Boolean : Chaînes littérales true ou false (en minuscules).

Modèle de sécurité

Le modèle de sécurité empêche les utilisateurs finaux d’effectuer des appels API sans le secret partagé. Le paramètre securitySalt (situé dans /etc/bigbluebutton/bbb-web.properties) sert de secret partagé et ne doit jamais être exposé aux utilisateurs finaux.

Génération du checksum

1. Créer la chaîne de requête sans checksum (ex : name=Test+Meeting&meetingID=abc123)
2. Préfixer avec le nom de l’appel API (ex : createname=Test+Meeting&meetingID=abc123)
3. Ajouter le secret partagé à la fin (ex : createname=Test+Meeting&meetingID=abc123639259d4...)
4. Générer un hash SHA-1 de la chaîne combinée
5. Ajouter le paramètre checksum à la chaîne de requête

Le checksum doit être inclus avec chaque appel API.

Ressources de l’API

Administration

Monitoring

Enregistrements

Réponse standard

Chaque réponse de l’API contient :

• returncode : SUCCESS ou FAILED
• message : Informations complémentaires (le cas échéant)
• messageKey : Identifiant d’erreur lisible par les machines

create

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/create?[paramètres]&checksum=[checksum]

Crée une réunion BigBlueButton. Cet appel est idempotent : l’appeler plusieurs fois avec des paramètres identiques retourne un succès sans effet secondaire.

Paramètres requis

Paramètres optionnels

Fonctionnalités désactivables

Chat : chat, privateChat, deleteChatMessage, editChatMessage, replyChatMessage, chatMessageReactions, chatEmojiPicker

Présentation & Tableau blanc : presentation, downloadPresentationWithAnnotations, downloadPresentationConvertedToPdf, downloadPresentationOriginalFile, snapshotOfCurrentSlide, infiniteWhiteboard

Sous-commissions : breakoutRooms, importPresentationWithAnnotationsFromBreakoutRooms, importSharedNotesFromBreakoutRooms

Vidéo & Audio : screenshare, cameraAsContent, virtualBackgrounds, customVirtualBackgrounds, liveTranscription, captions

Engagement : polls, quizzes, raiseHand, userReactions, externalVideos, timer

Notes partagées : sharedNotes

Analytics : learningDashboard, learningDashboardDownloadSessionData

Dispositions : layouts

Plugins : plugins

Exemple de requête

https://votre-serveur.com/bigbluebutton/api/create?name=Test&meetingID=test01&checksum=1234

Exemple de requête POST

curl --request POST \
  --url https://votre-serveur.com/bigbluebutton/api/create \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data welcome=Bienvenue \
  --data allowStartStopRecording=true \
  --data attendeePW=ap \
  --data autoStartRecording=false \
  --data meetingID=random-1730297 \
  --data moderatorPW=mp \
  --data name=random-1730297 \
  --data record=false \
  --data voiceBridge=71296 \
  --data checksum=1234

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>Test</meetingID>
  <internalMeetingID>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</internalMeetingID>
  <parentMeetingID>bbb-none</parentMeetingID>
  <attendeePW>ap</attendeePW>
  <moderatorPW>mp</moderatorPW>
  <createTime>1531155809613</createTime>
  <voiceBridge>70757</voiceBridge>
  <dialNumber>613-555-1234</dialNumber>
  <createDate>Mon Jul 09 17:03:29 UTC 2018</createDate>
  <hasUserJoined>false</hasUserJoined>
  <duration>0</duration>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
</response>

Pré-téléverser des slides (corps POST)

<modules>
  <module name="presentation">
    <document url="http://www.sample-pdf.com/sample.pdf"
              filename="rapport.pdf"/>
    <document name="sample-presentation.pdf">
      JVBERi0xLjQKJ... [contenu encodé en base64]
    </document>
  </module>
</modules>

Paramètres pour les documents (v2.5+) :

• downloadable : Boolean (défaut : false) - Permettre le téléchargement de la présentation
• removable : Boolean (défaut : true) - Permettre la suppression de la présentation

Callbacks

Callback de fin de réunion

Passer le paramètre meta_endCallbackUrl avec l’URL de callback encodée. BigBlueButton effectue une requête HTTPS GET quand la réunion se termine avec le paramètre recordingmarks=true|false.

Callback d’enregistrement prêt

Passer le paramètre meta_bbb-recording-ready-url. BigBlueButton effectue une requête HTTPS POST quand l’enregistrement est prêt. Le corps contient un paramètre signed_parameters encodé en JWT (algorithme HS256, signé avec le secret partagé).

Callback Learning Analytics Dashboard

Passer le paramètre meta_analytics-callback-url. BigBlueButton effectue une requête POST avec un corps JSON contenant les données analytics.

join

Méthodes : GET

https://votre-serveur.com/bigbluebutton/api/join?[paramètres]&checksum=[checksum]

Fait rejoindre un utilisateur dans une réunion existante.

Paramètres requis

Paramètres optionnels

Exemple de requête

https://votre-serveur.com/bigbluebutton/api/join?meetingID=test01&role=moderator&fullName=Jean&checksum=1234

Exemple de réponse (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
  <meeting_id>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</meeting_id>
  <user_id>w_euxnssffnsbs</user_id>
  <auth_token>14mm5y3eurjw</auth_token>
  <session_token>ai1wqj8wb6s7rnk0</session_token>
  <url>https://votre-serveur.com/client/BigBlueButton.html?sessionToken=ai1wqj8wb6s7rnk0</url>
</response>

insertDocument

Méthodes : POST

https://votre-serveur.com/bigbluebutton/api/insertDocument?[paramètres]&checksum=[checksum]

Insère des documents dans une réunion en cours.

Paramètres requis

Exemple de requête

curl -s -X POST \
  "https://votre-serveur.com/bigbluebutton/api/insertDocument?meetingID=Test&checksum=1234" \
  --header "Content-Type: application/xml" \
  --data '<modules>
  <module name="presentation">
    <document current="true" downloadable="true"
             url="https://example.com/doc.pdf"
             filename="sample.pdf"/>
  </module>
</modules>'

isMeetingRunning

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/isMeetingRunning?[paramètres]&checksum=[checksum]

Vérifie si une réunion est en cours.

Paramètres requis

Exemple de réponse

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

end

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/end?[paramètres]&checksum=[checksum]

Termine de force une réunion et retire tous les participants.

Paramètres requis

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>sentEndMeetingRequest</messageKey>
  <message>A request to end the meeting was sent. Please wait a few seconds, and then use getMeetingInfo or isMeetingRunning API calls to verify that it was ended.</message>
</response>

getMeetingInfo

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/getMeetingInfo?[paramètres]&checksum=[checksum]

Retourne les informations complètes d’une réunion, incluant la liste des participants, les heures de début/fin et les métadonnées.

Paramètres requis

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <meetingName>Salle de réunion</meetingName>
  <meetingID>test01</meetingID>
  <internalMeetingID>a0715c95...-1715261728123</internalMeetingID>
  <createTime>1715261728123</createTime>
  <voiceBridge>66052</voiceBridge>
  <running>true</running>
  <recording>true</recording>
  <participantCount>1</participantCount>
  <moderatorCount>1</moderatorCount>
  <attendees>
    <attendee>
      <userID>w_ftcrsyuh44oj</userID>
      <fullName>Jean Dupont</fullName>
      <role>MODERATOR</role>
      <isPresenter>true</isPresenter>
      <isListeningOnly>false</isListeningOnly>
      <hasJoinedVoice>true</hasJoinedVoice>
      <hasVideo>true</hasVideo>
      <clientType>HTML5</clientType>
    </attendee>
  </attendees>
  <isBreakout>false</isBreakout>
</response>

getMeetings

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/getMeetings?checksum=[checksum]

Liste toutes les réunions sur le serveur. Aucun paramètre requis.

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <meetings>
    <meeting>
      <meetingName>Demo Meeting</meetingName>
      <meetingID>Demo Meeting</meetingID>
      <running>false</running>
      <participantCount>0</participantCount>
      <moderatorCount>0</moderatorCount>
      <isBreakout>false</isBreakout>
    </meeting>
  </meetings>
</response>

getRecordings

Méthodes : GET

https://votre-serveur.com/bigbluebutton/api/getRecordings?[paramètres]&checksum=[checksum]

Récupère les enregistrements disponibles. Supporte la pagination (ajoutée en v2.6).

Paramètres optionnels

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <recordings>
    <recording>
      <recordID>ffbfc4cc...-1530718721124</recordID>
      <meetingID>c637ba21...</meetingID>
      <name>Salle de Fred</name>
      <published>true</published>
      <state>published</state>
      <startTime>1530718721124</startTime>
      <endTime>1530718810456</endTime>
      <participants>3</participants>
      <playback>
        <format>
          <type>presentation</type>
          <url>https://demo.bigbluebutton.org/playback/...</url>
          <processingTime>7177</processingTime>
          <length>0</length>
        </format>
      </playback>
    </recording>
  </recordings>
</response>

publishRecordings

Méthodes : GET

https://votre-serveur.com/bigbluebutton/api/publishRecordings?[paramètres]&checksum=[checksum]

Publie ou dépublie des enregistrements.

Paramètres requis

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <published>true</published>
</response>

deleteRecordings

Méthodes : GET

https://votre-serveur.com/bigbluebutton/api/deleteRecordings?[paramètres]&checksum=[checksum]

Supprime des enregistrements.

Paramètres requis

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <deleted>true</deleted>
</response>

updateRecordings

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/updateRecordings?[paramètres]&checksum=[checksum]

Met à jour les métadonnées d’un enregistrement.

Paramètres requis

Exemple de requête

https://votre-serveur.com/bigbluebutton/api/updateRecordings?recordID=record123&meta_Presenter=Jane%20Doe&meta_category=FINANCE&checksum=1234

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
  <updated>true</updated>
</response>

getRecordingTextTracks

Méthodes : GET, POST

https://votre-serveur.com/bigbluebutton/api/getRecordingTextTracks?[paramètres]&checksum=[checksum]

Liste les fichiers de sous-titres pour un enregistrement.

Paramètres requis

Exemple de réponse

{
  "response": {
    "returncode": "SUCCESS",
    "tracks": [
      {
        "href": "https://example.com/subtitles_en-US.vtt",
        "kind": "subtitles",
        "label": "English",
        "lang": "en-US",
        "source": "upload"
      },
      {
        "href": "https://example.com/subtitles_fr-FR.vtt",
        "kind": "subtitles",
        "label": "Francais",
        "lang": "fr-FR",
        "source": "upload"
      }
    ]
  }
}

Attributs d’une piste :

• kind : subtitles ou captions
• lang : Tag de langue RFC 5646 (ex : “fr-FR”, “en-US”)
• label : Label lisible affiché dans le lecteur
• source : live, automatic ou upload
• href : Lien de téléchargement WebVTT

putRecordingTextTrack

Méthodes : POST

POST https://votre-serveur.com/bigbluebutton/api/putRecordingTextTrack

Téléverse un fichier de sous-titres vers un enregistrement.

Paramètres requis (URI)

Corps POST

file : (Binaire, multipart/form-data) - Fichier de sous-titres

Formats acceptés : SRT (application/x-subrip), SSA/ASS, WebVTT (text/vtt)

Exemple de réponse

{
  "response": {
    "messageKey": "upload_text_track_success",
    "message": "Text track uploaded successfully",
    "recordId": "baz",
    "returncode": "SUCCESS"
  }
}

sendChatMessage

Méthodes : GET

https://votre-serveur.com/bigbluebutton/api/sendChatMessage?[paramètres]&checksum=[checksum]

Envoie un message dans le chat public d’une réunion en cours. Ajouté en v3.0.

Paramètres requis

Paramètres optionnels

Exemple de réponse

<response>
  <returncode>SUCCESS</returncode>
</response>