API-Version: 4.x neueste 3.x
Kapitel 21 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.

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 einschließlich Dateiendung für URL-basierte Uploads. Erforderlich, wenn der URL-Pfad nicht mit einem Dateinamen mit Dateiendung endet; andernfalls schlägt die Anfrage fehl.
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>
  <message>Presentation is being uploaded</message>
</response>

Eine SUCCESS-Antwort bestätigt lediglich, dass der Server die Anfrage angenommen hat. Download und Konvertierung erfolgen im Hintergrund; Fehler werden an die Meeting-Clients und das Serverprotokoll gemeldet, nicht in der API-Antwort.

Beschränkungen und Fehlerantworten BBB 4.0.1+

Seit BBB 4.0.1 werden mit einem einzelnen Aufruf höchstens 10 Dokumente hochgeladen (Servereinstellung maxPresentationsPerRequest). Das erste Dokument mit current="true" wird immer beibehalten, gefolgt von den übrigen in der Reihenfolge der Anfrage. Weitere Dokumente werden verworfen – returncode bleibt weiterhin SUCCESS, aber die Antwort enthält messageKey documentsDropped:

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>documentsDropped</messageKey>
  <message>...</message>
</response>

Die Aufrufrate ist außerdem pro Meeting begrenzt: standardmäßig 30 Aufrufe pro 60 Sekunden (insertDocumentMaxRequests, insertDocumentRateWindowSec). Jede FAILED-Antwort enthält jetzt messageKey:

messageKey Beschreibung
notFoundEs wurde kein Meeting mit der angegebenen Meeting-ID gefunden.
malformedXmlDer Anfragetext ist kein wohlgeformtes XML.
invalidPresentationUrlEine Dokument-URL entspricht nicht der gültigen URI-Syntax. Alle URLs werden geprüft, bevor die Dokumentenbegrenzung angewendet wird.
invalidFilenameEin Dateiname ist ungültig oder kann nicht aus der URL abgeleitet werden. Kein Dokument aus der Anfrage wird hochgeladen.
presentationDisabledDie Präsentationsfunktion ist für die Konferenz deaktiviert.
noDocumentsDer Anfragetext enthält kein presentation-Modul oder kein Dokument mit url oder name.
rateLimitExceededDas Meeting hat die zulässige Anzahl an Aufrufen innerhalb des Zeitfensters überschritten. Versuchen Sie es später erneut.

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, wenn auf dem Server kein Meeting mit der angegebenen ID existiert. Geprüft wird, ob das Meeting existiert, nicht, ob es läuft: Auch ein Meeting, das erstellt wurde, dem aber noch niemand beigetreten ist, akzeptiert Dokumente.

Es werden dieselben Formate wie beim regulären Präsentationsupload unterstützt, darunter PDF, PPTX, DOCX, ODT und gängige Bildformate. Office-Dokumente werden in PDF konvertiert, wobei LibreOffice verwendet wird; PDF-Dateien und Bilder werden direkt verarbeitet.

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.

Eine SUCCESS-Antwort bestätigt lediglich, dass der Server die Anfrage angenommen hat. Download und Konvertierung erfolgen im Hintergrund; Fehler werden an die Meeting-Clients und das Serverprotokoll gemeldet, nicht in der API-Antwort.