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.
bbbserver.de — IntegrationAPI
bbbserver.de est une plateforme d'hébergement premium basée dans l'UE pour BigBlueButton, avec des serveurs situés dans l'UE. Le IntegrationAPI est un proxy qui réplique entièrement l'API BBB standard — les applications externes s'y connectent via des plugins BBB standard et se comportent comme si elles communiquaient avec un seul serveur BBB. En coulisses, bbbserver répartit automatiquement les conférences sur plusieurs serveurs disposant d'une capacité suffisante.
Votre URL API et votre shared secret sont disponibles dans le panneau d'administration bbbserver sous Customer Settings → IntegrationAPI. Le IntegrationAPI peut y être activé ou désactivé.
Compatibilité Plugin
Les plateformes suivantes fonctionnent immédiatement — saisissez simplement l'URL API et le shared secret :
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Différences par rapport à l'API standard
| Sujet | Détail |
|---|---|
maxParticipants / duration | Utilisé pour la réservation de capacité, et pas seulement comme limite. Valeurs par défaut si non spécifié : 5 participants, 60 minutes. |
duration comportement | Ne met PAS automatiquement fin aux réunions — utilisé uniquement pour la planification de capacité. |
| Paramètre supplémentaire | deactivateBbbserverDefaultChatTexts — à des fins de white-labeling. |
| Points de terminaison indisponibles | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Spécifique à la réunion uniquement, avec obfuscation de la confidentialité. |
| Limites de débit | Aucune limitation de débit sur le IntegrationAPI. |
En plus de l'IntegrationAPI, bbbserver.de propose une System API distincte avec des fonctionnalités spécifiques à la plateforme telles que la gestion des comptes et les statistiques d'utilisation. La System API n'est pas compatible avec BBB et n'est pas couverte dans ce guide.