Vue d’ensemble de l’API
L'API BigBlueButton est une interface basée sur HTTP qui permet à des applications externes — telles que des systèmes de gestion de l'apprentissage, des portails web et des intégrations personnalisées — de créer, contrôler et surveiller des réunions par programmation. Tous les appels API sont sécurisés à l'aide d'un mécanisme checksum basé sur un shared secret.
Fonctionnement de l'API
L'API BBB suit un modèle simple requête-réponse. Vous envoyez une requête HTTPS à un point de terminaison spécifique sur votre serveur BigBlueButton, et le serveur répond avec un document XML indiquant le succès ou l'échec.
- Protocole : HTTPS (GET ou POST)
- URL de base :
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Format de réponse : XML (avec quelques exceptions qui renvoient JSON)
- Authentification : Shared-secret basée sur checksum (pas de OAuth, pas de clé API)
Catégories de points de terminaison
Les points de terminaison de l'API sont organisés dans les catégories suivantes :
| Catégorie | Points de terminaison | Description |
|---|---|---|
| Administration | create, join, end | Créer, rejoindre et terminer des réunions |
| Surveillance | isMeetingRunning, getMeetings, getMeetingInfo | Surveiller les réunions en cours |
| Enregistrements | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Gérer les enregistrements de réunion |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Notifications d'événements en temps réel |
| Messagerie | sendChatMessage | Envoyer des messages de chat BBB 3.0+ |
| Session | getJoinUrl, feedback | Gestion de session BBB 3.0+ |
Méthodes HTTP
La plupart des points de terminaison acceptent les requêtes GET et POST. Lors de l'utilisation de POST, notez que la checksum est calculée à partir de l'query string de l'URL, et non du corps de la requête. Le corps POST peut contenir des données supplémentaires telles que des XML de présentation ou des remplacements de paramètres client.
Même lors de l'envoi d'une requête POST, la checksum doit être calculée à partir des paramètres query string dans l'URL. Le contenu du corps n'est pas inclus dans le calcul de la checksum.
Format de réponse
Chaque réponse de l'API contient au moins les champs suivants :
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response>| Champ | Description |
|---|---|
returncode | Toujours SUCCESS ou FAILED |
messageKey | Code d'erreur lisible par machine (présent uniquement en cas d'erreurs ou d'avertissements) |
message | Description de l'erreur ou de l'avertissement lisible par l'humain |
Versionnement de l'API
L'API BigBlueButton n'utilise pas de versionnage traditionnel basé sur l'URL (pas de chemins /v1/, /v2/). À la place, de nouveaux paramètres sont ajoutés de manière rétrocompatible, et les paramètres obsolètes sont marqués en conséquence mais ne sont pas supprimés immédiatement.
| Version BBB | Modifications notables de l'API |
|---|---|
| 2.2 | paramètres Lock, allowModsToUnmuteUsers |
| 2.4 | logo, meetingLayout, allowModsToEjectCameras, Tableau de bord d'apprentissage |
| 2.5 | disabledFeatures, prise en charge de SHA-384/SHA-512, webhook eventID filtre |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, mode sombre |
| 2.7 | preUploadedPresentation (URL unique), pagination d'enregistrement |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role remplace password sur join |
Points de terminaison non documentés
Les points de terminaison suivants existent dans le code source BigBlueButton, mais ne sont pas couverts par la documentation officielle. Ils sont utilisés en interne et peuvent changer sans préavis.
| Point de terminaison | Méthode | Description | Statut |
|---|---|---|---|
/api/stuns | GET POST | Renvoie la configuration serveur STUN/TURN pour les connexions WebRTC | Undocumented |
/api/signOut | GET POST | Terminer la session / déconnecter l'utilisateur | Undocumented |
/api/guestWait | GET | Interroger l'état du lobby pour les invités en attente de l'approbation du modérateur | Undocumented |
/api/getSessions | GET POST | Récupérer les informations de session | Undocumented |
/api/learningDashboard | GET POST | Récupérer les données d'analyse de l'apprentissage | Undocumented |
Mutations GraphQL (actions en réunion)
Depuis BBB 3.0, la plupart des actions en temps réel au sein d'une réunion sont gérées via des mutations GraphQL sur WebSocket. Celles-ci sont utilisées en interne par le client HTML5 BBB et ne font pas partie de l'API REST classique.
| Catégorie | Nombre | Exemples |
|---|---|---|
| Discussion | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Gestion des utilisateurs | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Présentation | 11 | presentationSetCurrent, presentationSetPage |
| Contrôle de la réunion | 8 | meetingEnd, meetingRecordingSetStatus |
| Salles de répartition | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Sondages | 4 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Minuteur | 8 | timerStart, timerStop, timerReset |
| Extensions | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
La couche GraphQL est destinée à un usage interne du client et ne fournit pas d'API publique stable. Les mutations et leurs paramètres peuvent changer entre les versions BBB sans préavis.
Prérequis
Avant de pouvoir commencer à utiliser l'API BigBlueButton, assurez-vous d'avoir les éléments suivants en place :
Un serveur BigBlueButton en fonctionnement (version 3.0 recommandée)
Le secret partagé (également appelé "security salt"), configuré dans /etc/bigbluebutton/bbb-web.properties
Accès HTTPS au serveur
Une application côté serveur qui génère les appels API — le shared secret ne doit jamais être exposé côté client
N'exposez jamais le shared secret dans du code côté client (JavaScript, applications mobiles). Tous les appels API doivent être générés côté serveur afin d'empêcher tout accès non autorisé à votre serveur BigBlueButton.
Si vous utilisez bbbserver.de, consultez le chapitre bbbserver.de IntegrationAPI dédié pour la configuration du tableau de bord, la compatibilité des plugins et les différences par rapport à l’API standard.