Kapitel 20 POST

insertDocument – Präsentation einfügen

Der Endpunkt insertDocument ermöglicht es Ihnen, eine oder mehrere Präsentationen in ein bereits laufendes BigBlueButton-Meeting hochzuladen, ohne den aktuellen Präsentierenden zu unterbrechen. Dokumente werden im Hintergrund verarbeitet und stehen als zusätzliche Präsentationen zur Verfügung, zu denen der Präsentierende jederzeit wechseln kann.

Dieser Endpunkt ist in der offiziellen BigBlueButton-API-Dokumentation nur knapp dokumentiert. Details zu Fehlercodes, Dateigrößenbeschränkungen und dem genauen Antwort-XML sind offiziell nicht spezifiziert. undocumented

Endpunkt

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

Dieser Endpunkt erfordert eine POST-Anfrage mit einem XML-Body. Die Dokumentdaten werden im Anfrage-Body gesendet, nicht als URL-Parameter.

URL-Parameter

Parameter Typ Erforderlich Standard Beschreibung
meetingID String Ja — Die Meeting-ID des laufenden Meetings, das das Dokument erhalten soll.

XML-Body — Dokumentattribute

Der Anfrage-Body muss eine XML-Struktur mit einem <module name="presentation">-Element enthalten, das ein oder mehrere <document>-Elemente umschließt. Jedes Dokument kann entweder per URL oder als eingebetteter Base64-Inhalt hochgeladen werden.

Attribut Typ Erforderlich Standard Beschreibung
url String Nein — URL, die auf die Präsentationsdatei verweist. Wird für URL-basierte Uploads verwendet. Der Server ruft die Datei von dieser URL ab.
filename String Nein — Dateiname für URL-basierte Uploads. Hilft bei der Erkennung des Dateityps, wenn die URL keine Dateierweiterung enthält.
name String Nein — Dateiname für Base64-Inline-Uploads. Bei Verwendung dieses Attributs muss der Elementtext den Base64-kodierten Dateiinhalt enthalten.
current Boolean Nein false Wenn auf true gesetzt, wird diese Präsentation nach dem Upload sofort als aktuelle Präsentation aktiviert.
downloadable Boolean Nein false Wenn auf true gesetzt, dürfen Teilnehmende die Präsentationsdatei herunterladen.
removable Boolean Nein true Wenn auf true gesetzt, darf der Präsentierende die Präsentation aus dem Meeting entfernen.

Beispielanfrage — URL-basierter 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>'

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

Beispielantwort

Ein erfolgreicher Aufruf gibt das folgende XML zurück: 

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

Eine SUCCESS-Antwort bestätigt, dass das Dokument zur Verarbeitung angenommen wurde. Sie garantiert nicht, dass die Dateikonvertierung erfolgreich abgeschlossen wurde. Ob Konvertierungsfehler über die API-Antwort zurückgemeldet werden, ist offiziell nicht dokumentiert. undocumented

Vergleich mit dem create-Präsentations-Upload

Sie können Präsentationen auch während der Meeting-Erstellung mit dem Endpunkt create hochladen. Die folgende Tabelle hebt die Unterschiede zwischen den beiden Ansätzen hervor:

Aspekt create insertDocument
Zeitpunkt Bevor das Meeting beginnt Während das Meeting läuft
Unterbrechung Keine (erste Folie wird beim Beitritt geladen) Keine (Hintergrund-Upload)
current Attribut Unterstützt Unterstützt
Mehrere Dokumente Unterstützt Unterstützt

Tipps

Wenn die neue Präsentation sofort aktiv werden soll, setzen Sie current="true" auf dem Dokument-Element. Andernfalls muss der Präsentierende manuell über die Präsentationsauswahl in der Meeting-Oberfläche zu ihr wechseln.

  • Dieselben Dateiformate, die beim regulären Präsentations-Upload unterstützt werden, werden auch hier unterstützt (PDF, PPTX, DOCX, Bilder usw.).
  • Sie können mehrere Dokumente in einer einzelnen Anfrage einfügen, indem Sie weitere Dokument-Elemente innerhalb des Modul-Blocks hinzufügen.
  • Setzen Sie bei URL-basierten Uploads immer das Attribut filename, wenn die URL keine erkennbare Dateiendung enthält. Dies hilft BigBlueButton, den korrekten Dateityp zu bestimmen.
  • Für große Dateien wird ein URL-basierter Upload gegenüber einem Base64-Inline-Upload empfohlen, damit die Nutzlast der Anfrage klein bleibt.

Anwendungsfälle

  • Stellen Sie während einer Live-Sitzung Folien dynamisch aus einem LMS oder Content-Management-System bereit.
  • Fügen Sie ergänzendes Material zu einem Meeting hinzu, nachdem es bereits begonnen hat.
  • Erstellen Sie automatisierte Bots, die Agenden, Besprechungsnotizen oder Berichte in laufende Meetings einfügen.
  • Ermöglichen Sie externen Systemen, aktualisierte Inhalte zu übertragen, ohne dass der Präsentierende das Meeting verlassen muss.
Auf bbbserver.de ist dieser Endpunkt in allen Tarifen verfügbar. Sie können ihn mit Ihren API-Zugangsdaten aufrufen, die Sie im Server-Management-Dashboard finden. Es gelten dieselben Dateigrößenbeschränkungen wie für normale Präsentations-Uploads.

Häufig gestellte Fragen

Der Endpunkt insertDocument ist in BigBlueButton 2.5 und später verfügbar. In älteren Versionen wie 2.4 oder früher ist er nicht verfügbar.

Ja, wenn das Attribut removable auf true gesetzt wurde (was der Standard ist). Der Präsentierende kann die Präsentation über die Meeting-Oberfläche entfernen. Es gibt keinen dedizierten API-Endpunkt, um eine Präsentation aus einem laufenden Meeting zu entfernen.

Die API gibt eine FAILED-Antwort zurück, die angibt, dass das Meeting nicht gefunden wurde. Dokumente können nur in Meetings eingefügt werden, die aktuell laufen.

Es werden dieselben Formate wie beim regulären Präsentations-Upload unterstützt, einschließlich PDF, PPTX, DOCX, ODT und gängiger Bildformate. Der Server konvertiert Dateien, die nicht PDF sind, intern mit PDF in LibreOffice.

Dateigrößenbeschränkungen werden durch die BigBlueButton-Serverkonfiguration bestimmt. Die genauen Limits werden nicht über die API spezifiziert und hängen von serverseitigen Einstellungen ab. Wenden Sie sich für Details an Ihren Serveradministrator.

Sie können einen Breakout-Raum ansprechen, indem Sie dessen spezifische meetingID verwenden. Jeder Breakout-Raum hat eine eigene eindeutige Meeting-Kennung, die über den Endpunkt getMeetings oder getMeetingInfo abgerufen werden kann.

Nein. Eine SUCCESS-Antwort bestätigt nur, dass der Server das Dokument zur Verarbeitung angenommen hat. Ob die Konvertierung erfolgreich war, wird in der API-Antwort nicht zuverlässig gemeldet. Dieses Verhalten ist offiziell nicht dokumentiert.