Hoofdstuk 20 POST

insertDocument – Presentatie invoegen

Met het insertDocument-endpoint kun je een of meer presentaties uploaden naar een al lopende BigBlueButton-vergadering zonder de huidige presentator te onderbreken. Documenten worden op de achtergrond verwerkt en worden beschikbaar als extra presentaties waarnaar de presentator op elk moment kan overschakelen.

Dit endpoint is slechts beperkt gedocumenteerd in de officiële BigBlueButton-API-documentatie. Details over foutcodes, bestandsgroottelimieten en het exacte antwoord-XML zijn niet officieel gespecificeerd. undocumented

Endpoint

POST https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum
Content-Type: application/xml

Dit endpoint vereist een POST-verzoek met een XML-body. De documentgegevens worden in de requestbody verzonden, niet als URL-parameters.

URL-parameters

Parameter Type Vereist Standaard Beschrijving
meetingID String Ja — De vergaderings-ID van de lopende vergadering die het document moet ontvangen.

XML-body — documentattributen

De requestbody moet een XML-structuur bevatten met een <module name="presentation">-element dat één of meer <document>-elementen omvat. Elk document kan worden geüpload via een URL of als inline Base64-inhoud.

Attribuut Type Vereist Standaard Beschrijving
url String Nee — URL die naar het presentatiebestand verwijst. Gebruikt voor URL-gebaseerde uploads. De server haalt het bestand op vanaf deze URL.
filename String Nee — Bestandsnaam voor URL-gebaseerde uploads. Helpt bij de detectie van het bestandstype wanneer de URL geen bestandsextensie bevat.
name String Nee — Bestandsnaam voor Base64-inline-uploads. Bij gebruik van dit attribuut moet de elementtekst de met Base64 gecodeerde bestandsinhoud bevatten.
current Boolean Nee false Wanneer ingesteld op true, wordt deze presentatie direct geactiveerd als de huidige presentatie na het uploaden.
downloadable Boolean Nee false Wanneer ingesteld op true, mogen deelnemers het presentatiebestand downloaden.
removable Boolean Nee true Wanneer ingesteld op true, mag de presentator de presentatie uit de vergadering verwijderen.

Voorbeeldverzoek — URL-gebaseerde upload

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>'

Voorbeeldverzoek — Base64-inline-upload

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>'

Voorbeeldrespons

Een succesvolle aanroep retourneert de volgende XML: 

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

Een SUCCESS-antwoord bevestigt dat het document is geaccepteerd voor verwerking. Het garandeert niet dat de bestandsconversie succesvol is voltooid. Of conversiefouten via het API-antwoord worden teruggekoppeld, is niet officieel gedocumenteerd. undocumented

Vergelijking met create-presentatie-upload

Je kunt ook presentaties uploaden tijdens het aanmaken van een vergadering met het endpoint create. De volgende tabel benadrukt de verschillen tussen de twee benaderingen:

Aspect create insertDocument
Timing Voordat de vergadering begint Terwijl de vergadering loopt
Onderbreking Geen (eerste dia wordt geladen bij deelname) Geen (upload op de achtergrond)
current attribuut Ondersteund Ondersteund
Meerdere documenten Ondersteund Ondersteund

Tips

Als je wilt dat de nieuwe presentatie onmiddellijk actief wordt, stel dan current="true" in op het documentelement. Anders moet de presentator er handmatig naartoe schakelen via de presentatieselector in de vergaderinterface.

  • Dezelfde bestandsformaten die worden ondersteund door de reguliere presentatie-upload worden hier ook ondersteund (PDF, PPTX, DOCX, afbeeldingen, enz.).
  • Je kunt meerdere documenten in één verzoek invoegen door meer documentelementen binnen het moduleblok toe te voegen.
  • Stel bij URL-gebaseerde uploads altijd het attribuut filename in wanneer de URL geen herkenbare bestandsextensie bevat. Dit helpt BigBlueButton om het juiste bestandstype te bepalen.
  • Voor grote bestanden wordt URL-gebaseerde upload aanbevolen boven Base64-inline-upload om de payload van het verzoek klein te houden.

Toepassingen

  • Lever tijdens een live sessie dynamisch dia's aan vanuit een LMS of contentmanagementsysteem.
  • Voeg aanvullend materiaal toe aan een vergadering nadat deze al is gestart.
  • Bouw geautomatiseerde bots die agenda's, vergadernotities of rapporten in lopende vergaderingen invoegen.
  • Sta externe systemen toe om bijgewerkte inhoud te pushen zonder dat de presentator de vergadering hoeft te verlaten.
Op bbbserver.de is dit endpoint beschikbaar bij alle abonnementen. Je kunt het aanroepen met je API-referenties die je vindt in het serverbeheerdashboard. Dezelfde bestandsgroottelimieten als bij gewone presentatie-uploads zijn van toepassing.

Veelgestelde vragen

Het insertDocument-endpoint is beschikbaar in BigBlueButton 2.5 en later. Het is niet beschikbaar in oudere versies zoals 2.4 of eerder.

Ja, als het attribuut removable op true was ingesteld (de standaardwaarde). De presentator kan de presentatie verwijderen via de vergaderinterface. Er is geen speciaal API-endpoint om een presentatie uit een lopende vergadering te verwijderen.

De API retourneert een FAILED-antwoord dat aangeeft dat de vergadering niet is gevonden. Documenten kunnen alleen worden ingevoegd in vergaderingen die momenteel lopen.

Dezelfde formaten als bij de reguliere presentatie-upload worden ondersteund, waaronder PDF, PPTX, DOCX, ODT en gangbare afbeeldingsformaten. De server converteert niet-PDF-bestanden intern naar PDF met behulp van LibreOffice.

Bestandsgroottelimieten worden bepaald door de configuratie van de BigBlueButton-server. De exacte limieten worden niet via de API gespecificeerd en zijn afhankelijk van serverinstellingen. Neem contact op met je serverbeheerder voor details.

Je kunt een breakout room targeten door de specifieke meetingID ervan te gebruiken. Elke breakout room heeft een eigen unieke vergader-ID die kan worden verkregen via het getMeetings- of getMeetingInfo-endpoint.

Nee. Een SUCCESS-antwoord bevestigt alleen dat de server het document voor verwerking heeft geaccepteerd. Of de conversie is geslaagd, wordt niet betrouwbaar gerapporteerd in het API-antwoord. Dit gedrag is niet officieel gedocumenteerd.