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 de archivo para cargas basadas en URL. Ayuda con la detección del tipo de archivo cuando la URL no contiene una extensión de archivo.
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>
</response>

Una respuesta SUCCESS confirma que el documento fue aceptado para su procesamiento. No garantiza que la conversión del archivo se haya completado correctamente. No está documentado oficialmente si los errores de conversión se informan de vuelta a través de la respuesta de la API. undocumented

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 devolverá una respuesta FAILED indicando que no se encontró la reunión. Los documentos solo pueden insertarse en reuniones que estén actualmente en curso.

Se admiten los mismos formatos que en la carga normal de presentaciones, incluidos PDF, PPTX, DOCX, ODT y formatos de imagen comunes. El servidor convierte internamente los archivos que no son PDF a PDF usando LibreOffice.

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.

No. Una respuesta SUCCESS solo confirma que el servidor aceptó el documento para su procesamiento. No se informa de forma fiable en la respuesta de la API si la conversión tuvo éxito. Este comportamiento no está documentado oficialmente.