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.
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
filenamecuando 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.
Preguntas frecuentes
insertDocument está disponible en BigBlueButton 2.5 y posteriores. No está disponible en versiones anteriores como 2.4 o anteriores.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.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.meetingID específico. Cada sala de grupos tiene su propio identificador de reunión único que puede obtenerse mediante el endpoint getMeetings o getMeetingInfo.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.