Chapter 20 POST

insertDocument – Insert Presentation

The insertDocument endpoint allows you to upload one or more presentations into an already running BigBlueButton meeting without interrupting the current presenter. Documents are processed in the background and become available as additional presentations that the presenter can switch to at any time.

This endpoint is only lightly documented in the official BigBlueButton API documentation. Details on error codes, file size limits, and the exact response XML are not officially specified. undocumented

Endpoint

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

This endpoint requires a POST request with an XML body. The document data is sent in the request body, not as URL parameters.

URL Parameters

Parameter Type Required Default Description
meetingID String Yes — The meeting identifier of the running meeting that should receive the document.

XML Body — Document Attributes

The request body must contain an XML structure with a <module name="presentation"> element wrapping one or more <document> elements. Each document can be uploaded either by URL or as inline Base64 content.

Attribute Type Required Default Description
url String No — URL pointing to the presentation file. Used for URL-based uploads. The server fetches the file from this URL.
filename String No — Filename for URL-based uploads. Helps with file type detection when the URL does not contain a file extension.
name String No — Filename for Base64 inline uploads. When using this attribute, the element text must contain the Base64-encoded file content.
current Boolean No false When set to true, this presentation is immediately activated as the current presentation after upload.
downloadable Boolean No false When set to true, participants are allowed to download the presentation file.
removable Boolean No true When set to true, the presenter is allowed to remove the presentation from the meeting.

Example Request — URL-based 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>'

Example Request — 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>'

Example Response

A successful call returns the following XML: 

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

A SUCCESS response confirms that the document was accepted for processing. It does not guarantee that the file conversion completed successfully. Whether conversion errors are reported back via the API response is not officially documented. undocumented

Comparison with create Presentation Upload

You can also upload presentations during meeting creation using the create endpoint. The following table highlights the differences between the two approaches:

Aspect create insertDocument
Timing Before the meeting starts While the meeting is running
Interruption None (first slide is loaded on join) None (background upload)
current attribute Supported Supported
Multiple documents Supported Supported

Tips

If you want the new presentation to become active immediately, set current="true" on the document element. Otherwise the presenter must manually switch to it using the presentation selector in the meeting interface.

  • The same file formats supported by the regular presentation upload are also supported here (PDF, PPTX, DOCX, images, etc.).
  • You can insert multiple documents in a single request by adding more document elements inside the module block.
  • For URL-based uploads, always set the filename attribute when the URL does not contain a recognizable file extension. This helps BigBlueButton determine the correct file type.
  • For large files, URL-based upload is recommended over Base64 inline upload to keep the request payload small.

Use Cases

  • Dynamically deliver slides from an LMS or content management system during a live session.
  • Add supplementary material to a meeting after it has already started.
  • Build automated bots that insert agendas, meeting notes, or reports into running meetings.
  • Allow external systems to push updated content without requiring the presenter to leave the meeting.
On bbbserver.de, this endpoint is available on all plans. You can call it using your API credentials found in the server management dashboard. The same file size limits as regular presentation uploads apply.

Frequently Asked Questions

The insertDocument endpoint is available in BigBlueButton 2.5 and later. It is not available in older versions such as 2.4 or earlier.

Yes, if the removable attribute was set to true (which is the default). The presenter can remove the presentation through the meeting interface. There is no dedicated API endpoint for removing a presentation from a running meeting.

The API will return a FAILED response indicating that the meeting was not found. Documents can only be inserted into meetings that are currently running.

The same formats as the regular presentation upload are supported, including PDF, PPTX, DOCX, ODT, and common image formats. The server converts non-PDF files to PDF internally using LibreOffice.

File size limits are determined by the BigBlueButton server configuration. The exact limits are not specified via the API and depend on server-side settings. Contact your server administrator for details.

You can target a breakout room by using its specific meetingID. Each breakout room has its own unique meeting identifier that can be obtained via the getMeetings or getMeetingInfo endpoint.

No. A SUCCESS response only confirms that the server accepted the document for processing. Whether the conversion succeeded is not reliably reported in the API response. This behavior is not officially documented.