Versión de la API: 4.x más reciente 3.x

Estás viendo la documentación de la API de BigBlueButton 3.x. La versión actual es BigBlueButton 4.x. ¿Planeas una actualización? La guía de migración enumera todos los cambios que necesitan tus llamadas a la API.

Capítulo 20 POST

insertDocument – Insertar presentación

El endpoint insertDocument le permite cargar una o más presentaciones en una reunión de BigBlueButton que ya está en curso sin interrumpir al presentador actual. Los documentos se procesan en segundo plano y quedan disponibles como presentaciones adicionales a las que el presentador puede cambiar en cualquier momento.

Este endpoint solo está documentado de forma ligera en la documentación oficial de la API de BigBlueButton. Los detalles sobre los códigos de error, los límites de tamaño de archivo y la respuesta exacta XML no están especificados oficialmente. undocumented

Endpoint

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

Este endpoint requiere una solicitud POST con un cuerpo XML. Los datos del documento se envían en el cuerpo de la solicitud, no como parámetros de URL.

Parámetros de URL

Parámetro Tipo Obligatorio Predeterminado Descripción
meetingID String Sí — El identificador de la reunión en ejecución que debe recibir el documento.

Cuerpo XML — Atributos del documento

El cuerpo de la solicitud debe contener una estructura XML con un elemento <module name="presentation"> que envuelva uno o más elementos <document>. Cada documento puede cargarse ya sea por URL o como contenido Base64 en línea.

Atributo Tipo Obligatorio Predeterminado Descripción
url String No — URL que apunta al archivo de presentación. Se utiliza para cargas basadas en URL. El servidor obtiene el archivo desde esta URL.
filename String No — Nombre del archivo, incluida la extensión, para cargas mediante URL. Es obligatorio cuando la ruta de la URL no termina en un nombre de archivo con extensión; de lo contrario, la solicitud falla.
name String No — Nombre de archivo para cargas Base64 en línea. Al usar este atributo, el texto del elemento debe contener el contenido del archivo codificado en Base64.
current Boolean No false Cuando se establece en true, esta presentación se activa inmediatamente como la presentación actual después de la carga.
downloadable Boolean No false Cuando se establece en true, se permite a los participantes descargar el archivo de presentación.
removable Boolean No true Cuando se establece en true, se permite al presentador eliminar la presentación de la reunión.

Solicitud de ejemplo — Carga basada en URL

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

Solicitud de ejemplo — Carga en línea de Base64

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

Respuesta de ejemplo

Una llamada correcta devuelve el siguiente XML:

<response>
  <returncode>SUCCESS</returncode>
  <message>Presentation is being uploaded</message>
</response>

Una respuesta SUCCESS solo confirma que el servidor ha aceptado la solicitud. La descarga y la conversión se ejecutan en segundo plano; los errores se notifican a los clientes de la reunión y se registran en el registro del servidor, no en la respuesta de la API.

Comparación con la carga de presentaciones de create

También puede cargar presentaciones durante la creación de la reunión usando el endpoint create. La siguiente tabla destaca las diferencias entre ambos enfoques:

Aspecto create insertDocument
Momento Antes de que comience la reunión Mientras la reunión está en curso
Interrupción Ninguna (la primera diapositiva se carga al unirse) Ninguna (carga en segundo plano)
current atributo Compatible Compatible
Múltiples documentos Compatible Compatible

Consejos

Si quieres que la nueva presentación se active inmediatamente, establece current="true" en el elemento del documento. De lo contrario, el presentador tendrá que cambiar manualmente a ella usando el selector de presentaciones en la interfaz de la reunión.

  • Los mismos formatos de archivo compatibles con la carga normal de presentaciones también son compatibles aquí (PDF, PPTX, DOCX, imágenes, etc.).
  • Puedes insertar múltiples documentos en una sola solicitud añadiendo más elementos de documento dentro del bloque del módulo.
  • Para cargas basadas en URL, establezca siempre el atributo filename cuando la URL no contenga una extensión de archivo reconocible. Esto ayuda a BigBlueButton a determinar el tipo de archivo correcto.
  • Para archivos grandes, se recomienda la carga basada en URL en lugar de la carga en línea de Base64 para mantener pequeño el tamaño de la carga útil de la solicitud.

Casos de uso

  • Entrega diapositivas dinámicamente desde un LMS o un sistema de gestión de contenidos durante una sesión en vivo.
  • Añade material complementario a una reunión después de que ya haya comenzado.
  • Crea bots automatizados que inserten agendas, notas de la reunión o informes en reuniones en curso.
  • Permite que sistemas externos envíen contenido actualizado sin requerir que el presentador abandone la reunión.
En bbbserver.de, este endpoint está disponible en todos los planes. Puedes llamarlo usando tus credenciales de API que se encuentran en el panel de administración del servidor. Se aplican los mismos límites de tamaño de archivo que para las cargas normales de presentaciones.

Preguntas frecuentes

El endpoint insertDocument está disponible en BigBlueButton 2.5 y posteriores. No está disponible en versiones anteriores como 2.4 o anteriores.

Sí, si el atributo removable se estableció en true (que es el valor predeterminado). El presentador puede eliminar la presentación a través de la interfaz de la reunión. No existe un endpoint de API dedicado para eliminar una presentación de una reunión en curso.

La API devuelve una respuesta FAILED si no existe ninguna reunión con el ID indicado en el servidor. Se comprueba si la reunión existe, no si está en curso: una reunión que se ha creado pero a la que todavía no se ha unido nadie también acepta documentos.

Se admiten los mismos formatos que en la carga habitual de presentaciones, incluidos PDF, PPTX, DOCX, ODT y los formatos de imagen comunes. Los documentos de Office se convierten a PDF mediante LibreOffice; los archivos PDF y las imágenes se procesan directamente.

Los límites de tamaño de archivo están determinados por la configuración del servidor BigBlueButton. Los límites exactos no se especifican a través de la API y dependen de la configuración del lado del servidor. Contacte con el administrador de su servidor para obtener más detalles.

Puede dirigirse a una sala de grupos usando su meetingID específico. Cada sala de grupos tiene su propio identificador de reunión único que puede obtenerse mediante el endpoint getMeetings o getMeetingInfo.

Una respuesta SUCCESS solo confirma que el servidor ha aceptado la solicitud. La descarga y la conversión se ejecutan en segundo plano; los errores se notifican a los clientes de la reunión y se registran en el registro del servidor, no en la respuesta de la API.