Vous consultez la documentation de l’API pour BigBlueButton 3.x. La version actuelle est BigBlueButton 4.x. Vous prévoyez une mise à niveau ? Le guide de migration répertorie toutes les modifications à apporter à vos appels API.
insertDocument – Insérer une présentation
Le point de terminaison insertDocument vous permet de téléverser une ou plusieurs présentations dans une réunion BigBlueButton déjà en cours sans interrompre le présentateur actuel. Les documents sont traités en arrière-plan et deviennent disponibles comme présentations supplémentaires vers lesquelles le présentateur peut basculer à tout moment.
Ce point de terminaison n’est que légèrement documenté dans la documentation officielle de l’API BigBlueButton. Les détails sur les codes d’erreur, les limites de taille de fichier et le XML exact de la réponse ne sont pas officiellement spécifiés. undocumented
Point de terminaison
POST https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum
Content-Type: application/xml Ce point de terminaison nécessite une requête POST avec un corps XML. Les données du document sont envoyées dans le corps de la requête, et non comme paramètres d’URL.
Paramètres d’URL
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
meetingID | String | Oui | — | L’identifiant de la réunion en cours qui doit recevoir le document. |
Corps XML — Attributs du document
Le corps de la requête doit contenir une structure XML avec un élément <module name="presentation"> englobant un ou plusieurs éléments <document>. Chaque document peut être téléversé soit par URL, soit comme contenu Base64 intégré.
| Attribut | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
url | String | Non | — | URL pointant vers le fichier de présentation. Utilisée pour les téléversements basés sur une URL. Le serveur récupère le fichier depuis cette URL. |
filename | String | Non | — | Nom du fichier avec son extension, pour les téléversements à partir d’une URL. Obligatoire lorsque le chemin de l’URL ne se termine pas par un nom de fichier avec une extension ; sinon, la requête échoue. |
name | String | Non | — | Nom de fichier pour les téléversements intégrés Base64. Lors de l’utilisation de cet attribut, le texte de l’élément doit contenir le contenu du fichier encodé en Base64. |
current | Boolean | Non | false | Lorsqu’elle est définie sur true, cette présentation est immédiatement activée comme présentation actuelle après le téléversement. |
downloadable | Boolean | Non | false | Lorsqu’elle est définie sur true, les participants sont autorisés à télécharger le fichier de présentation. |
removable | Boolean | Non | true | Lorsqu’elle est définie sur true, le présentateur est autorisé à supprimer la présentation de la réunion. |
Exemple de requête — Téléversement basé sur une URL
curl --request POST \
--url "https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum" \
--header "Content-Type: application/xml" \
--data '<?xml version="1.0" encoding="UTF-8"?>
<modules>
<module name="presentation">
<document url="https://api-guide.bbbserver.com/files/slides.pdf" filename="slides.pdf"
downloadable="true" removable="true" current="true"/>
</module>
</modules>' Exemple de requête — Téléversement intégré Base64
curl --request POST \
--url "https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum" \
--header "Content-Type: application/xml" \
--data '<?xml version="1.0" encoding="UTF-8"?>
<modules>
<module name="presentation">
<document name="inline-slides.pdf">
JVBERi0xLjQK... (Base64-encoded content)
</document>
</module>
</modules>' Exemple de réponse
Un appel réussi renvoie le XML suivant :
<response>
<returncode>SUCCESS</returncode>
<message>Presentation is being uploaded</message>
</response> Une réponse SUCCESS confirme uniquement que le serveur a accepté la requête. Le téléchargement et la conversion s’exécutent en arrière-plan ; les erreurs sont signalées aux clients de la réunion et consignées dans le journal du serveur, et non dans la réponse de l’API.
Comparaison avec le téléversement de présentation create
Vous pouvez également téléverser des présentations lors de la création de la réunion à l’aide du point de terminaison create. Le tableau suivant met en évidence les différences entre les deux approches :
| Aspect | create | insertDocument |
|---|---|---|
| Moment | Avant le début de la réunion | Pendant que la réunion est en cours |
| Interruption | Aucune (la première diapositive est chargée à la connexion) | Aucune (téléversement en arrière-plan) |
current attribut | Pris en charge | Pris en charge |
| Documents multiples | Pris en charge | Pris en charge |
Conseils
Si vous voulez que la nouvelle présentation devienne active immédiatement, définissez current="true" sur l’élément document. Sinon, le présentateur devra y basculer manuellement à l’aide du sélecteur de présentation dans l’interface de réunion.
- Les mêmes formats de fichier pris en charge par le téléversement de présentation classique sont également pris en charge ici (PDF, PPTX, DOCX, images, etc.).
- Vous pouvez insérer plusieurs documents dans une seule requête en ajoutant davantage d’éléments document à l’intérieur du bloc module.
- Pour les téléversements basés sur une URL, définissez toujours l’attribut
filenamelorsque l’URL ne contient pas une extension de fichier reconnaissable. Cela aide BigBlueButton à déterminer le type de fichier correct. - Pour les fichiers volumineux, le téléversement par URL est recommandé plutôt que le téléversement intégré Base64 afin de garder une petite charge utile de requête.
Cas d’usage
- Fournissez dynamiquement des diapositives depuis un LMS ou un système de gestion de contenu pendant une session en direct.
- Ajoutez du matériel complémentaire à une réunion après qu’elle a déjà commencé.
- Créez des bots automatisés qui insèrent des ordres du jour, des notes de réunion ou des rapports dans des réunions en cours.
- Permettez à des systèmes externes de pousser du contenu mis à jour sans obliger le présentateur à quitter la réunion.
Foire aux questions
insertDocument est disponible dans BigBlueButton 2.5 et les versions ultérieures. Il n’est pas disponible dans les anciennes versions telles que 2.4 ou antérieures.removable a été défini sur true (ce qui est la valeur par défaut). Le présentateur peut supprimer la présentation via l’interface de réunion. Il n’existe pas de point de terminaison API dédié pour supprimer une présentation d’une réunion en cours.FAILED si aucune réunion correspondant à l’identifiant fourni n’existe sur le serveur. La vérification porte sur l’existence de la réunion, et non sur le fait qu’elle soit en cours : une réunion créée mais que personne n’a encore rejointe accepte également les documents.meetingID spécifique. Chaque salle de sous-commission possède son propre identifiant de réunion unique, qui peut être obtenu via le point de terminaison getMeetings ou getMeetingInfo.SUCCESS confirme uniquement que le serveur a accepté la requête. Le téléchargement et la conversion s’exécutent en arrière-plan ; les erreurs sont signalées aux clients de la réunion et consignées dans le journal du serveur, et non dans la réponse de l’API.