API version: 4.x latest 3.x

You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.

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 including the extension, for URL-based uploads. Required when the URL path does not end in a filename with an extension; otherwise the request fails.
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>
  <message>Presentation is being uploaded</message>
</response>

A SUCCESS response only confirms that the server accepted the request. Download and conversion run in the background; errors are reported to the meeting clients and the server log, not in the API response.

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 returns a FAILED response if no meeting with the given ID exists on the server. The check is whether the meeting exists, not whether it is running: a meeting that has been created but not yet joined also accepts documents.

The same formats as the regular presentation upload are supported, including PDF, PPTX, DOCX, ODT, and common image formats. Office documents are converted to PDF using LibreOffice; PDF files and images are processed directly.

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.

A SUCCESS response only confirms that the server accepted the request. Download and conversion run in the background; errors are reported to the meeting clients and the server log, not in the API response.