Capítulo 21

Consejos, buenas prácticas y funciones ocultas

Este capítulo recopila funciones menos conocidas de la API, recomendaciones de seguridad y mejores prácticas comprobadas para integrarse con la API de BigBlueButton. Muchos de estos detalles solo están documentados parcialmente en las fuentes oficiales y han sido verificados mediante análisis del código fuente e investigación de la comunidad.

Valor oculto de la política de invitados

Además de los tres valores bien conocidos para el parámetro guestPolicy, existe un cuarto valor que rara vez se documenta pero que es muy útil para escenarios con audiencias mixtas.

Valor Comportamiento
ALWAYS_ACCEPT Todos los usuarios se unen inmediatamente sin aprobación.
ALWAYS_DENY Solo los moderadores pueden unirse a la reunión.
ASK_MODERATOR Los invitados esperan en la sala de espera hasta que un moderador los apruebe.
ALWAYS_ACCEPT_AUTH Los usuarios autenticados se unen directamente. Solo los invitados no autenticados requieren aprobación del moderador.

La política ALWAYS_ACCEPT_AUTH es ideal cuando los usuarios registrados de un LMS deben unirse sin esperar, mientras que los invitados externos todavía necesitan ser aprobados por un moderador.

Callback del lado del servidor con meetingEndedURL

El parámetro meetingEndedURL proporciona un callback del lado del servidor que difiere del meta_endCallbackUrl usado habitualmente en aspectos importantes:

  • No se expone al cliente ni se almacena en las grabaciones.
  • Se utiliza internamente por sistemas como Scalelite.
  • Es muy adecuado para integraciones del lado del servidor en las que la URL de callback debe permanecer oculta.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Parámetros de captura de salas de grupos

Más allá de los parámetros estándar de las salas de grupos, BigBlueButton admite opciones adicionales para recuperar contenido de las salas de grupos hacia la reunión principal.

Parámetro Tipo Descripción
breakoutRoomsCaptureSlides Boolean Importar diapositivas desde las salas de grupos a la reunión principal.
breakoutRoomsCaptureNotes Boolean Importar notas compartidas desde las salas de grupos a la reunión principal.
breakoutRoomsCaptureNotesFilename String Nombre de archivo personalizado para el archivo de notas capturado.

Parámetros de anotación y marca

El parámetro lockSettingsHideViewersAnnotation oculta las anotaciones de la pizarra realizadas por otros espectadores, de modo que cada participante solo vea sus propias anotaciones y las del presentador. 

create?meetingID=replace-with-meeting-id&lockSettingsHideViewersAnnotation=true&checksum=replace-with-checksum

El parámetro copyright establece un texto de copyright personalizado en el cliente BBB, lo que puede ser útil para implementaciones white-label: 

create?meetingID=replace-with-meeting-id&copyright=Example+Organization&checksum=replace-with-checksum

El parámetro logo solo funciona si displayBrandingArea=true está establecido en el archivo de configuración del servidor /etc/bigbluebutton/bbb-web.properties.

Mejores prácticas de seguridad

Incluye siempre createTime en las URL de unión

Incluya siempre el valor createTime de la respuesta de create en su URL de join. Esto evita que se reutilicen enlaces antiguos de join cuando se crea una nueva reunión con el mismo ID de reunión. 

join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&createTime=1715261728123&checksum=replace-with-checksum

Cálculo del checksum para solicitudes POST

Un error común: el checksum siempre se calcula solo a partir de la cadena de consulta de la URL, incluso para solicitudes POST. El cuerpo de la solicitud (XML, JSON) nunca se incluye en el cálculo del checksum. 

Checksum = SHA256("create" + "meetingID=replace-with-meeting-id&name=Demo" + "replace-with-secret")

El cuerpo POST (p. ej., presentación XML) se envía por separado, pero no se incluye en el hash.

Una vulnerabilidad de seguridad pasada (CVE GHSA-4m48-49h7-f3c4) permitió a atacantes con una URL de unión válida inyectar parámetros adicionales en enlaces de unión firmados. Valida y sanitiza siempre todos los parámetros del lado del servidor antes de generar URL API firmadas.

Cambios incompatibles de BBB 3.0

BigBlueButton 3.0 introduce varios cambios incompatibles que afectan a las integraciones de la API. Revisa cuidadosamente la siguiente tabla al actualizar:

Cambio Detalles
password → role La llamada join ahora usa role=MODERATOR o role=VIEWER en lugar de contraseñas.
POST eliminado para /join Solo se aceptan solicitudes GET para llamadas join.
Content-Type requerido Debe especificarse para todas las solicitudes POST.
Content-Types aceptado para /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Parámetros eliminados breakoutRoomsEnabled, learningDashboardEnabled y virtualBackgroundsDisabled han sido reemplazados por el parámetro disabledFeatures.

Endpoints obsoletos

Los siguientes endpoints están obsoletos y no deben usarse en integraciones nuevas:

Endpoint Estado Reemplazo
getDefaultConfigXML Obsoleto desde BBB 2.4, eliminado en BBB 3.0. clientSettingsOverride
setConfigXML Obsoleto desde BBB 2.4, eliminado en BBB 3.0. clientSettingsOverride

Comportamiento de fusión del manifiesto de plugins

Los manifiestos de plugins de tres fuentes se fusionan (no se sobrescriben) cuando se crea una reunión:

  1. Configuración del servidor
  2. Parámetro pluginManifests en la llamada create
  3. parámetro pluginManifestsFetchUrl

Los duplicados se eliminan automáticamente. Esto permite una configuración flexible de plugins en varios niveles.

Opciones importantes de configuración del servidor

Las siguientes configuraciones de bigbluebutton.properties no pueden controlarse mediante la API, pero afectan directamente al comportamiento de la API:

Propiedad Predeterminado Descripción
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Algoritmos de checksum compatibles para la autenticación de la API.
maxUserConcurrentAccesses 3 Número máximo de sesiones concurrentes por usuario (por ID externo).
allowOverrideClientSettingsOnCreateCall false Habilita el parámetro clientSettingsOverride en el cuerpo de create.
allowRevealOfBBBVersion false Muestra la versión de BBB en la respuesta raíz de la API.
allowFetchAllRecordings true Permite getRecordings sin un filtro de ID de reunión.
maxFileSizeUpload 30000000 Tamaño máximo de archivo para cargas de presentaciones (30 MB).
defaultHttpSessionTimeout 14400 Tiempo de espera de la sesión HTTP en segundos (4 horas).
sessionsCleanupDelayInMinutes 60 Las sesiones permanecen activas durante esta cantidad de minutos después de que termina una reunión.
fetchUrlSupportedProtocols https Protocolos permitidos para la obtención de URL (p. ej., descargas de presentaciones).

Configuración del Media Bridge

BigBlueButton 3.0 introduce LiveKit como puente multimedia alternativo. Los siguientes parámetros de create controlan qué puente se utiliza:

Parámetro Valores posibles Predeterminado
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Tiempo de espera de conversión de presentaciones

A partir de BBB 3.0, el parámetro del servidor maxPageConversionTime (predeterminado: 60 segundos) limita el tiempo de conversión por diapositiva. Las presentaciones complejas con muchas páginas o gráficos pesados pueden alcanzar este tiempo límite, provocando que las diapositivas no se conviertan.

Si sus presentaciones superan con frecuencia el tiempo de espera durante la conversión, considere dividirlas en archivos más pequeños o simplificar las diapositivas complejas antes de subirlas.

Preguntas frecuentes

Es un cuarto valor, menos conocido, para el parámetro guestPolicy. Los usuarios autenticados se unen inmediatamente, mientras que los invitados no autenticados deben esperar la aprobación del moderador. Esto es útil cuando los usuarios del LMS deben entrar directamente pero los visitantes externos necesitan ser examinados.

El parámetro meetingEndedURL es una devolución de llamada del lado del servidor que nunca se expone a los clientes ni se almacena en las grabaciones. Está diseñado para integraciones internas donde la URL de devolución de llamada debe permanecer privada, como en implementaciones de Scalelite.

No. El checksum siempre se calcula solo a partir de la cadena de consulta de la URL. El cuerpo POST (como la presentación XML) se envía por separado y no forma parte del hash. Esta es una fuente común de errores para los desarrolladores nuevos en la API.

En BigBlueButton 3.0, el parámetro password para la llamada join ha sido reemplazado por el parámetro role. Ahora pasas role=MODERATOR o role=VIEWER en lugar de la contraseña de asistente o moderador.

Incluir el valor createTime de la respuesta create garantiza que los enlaces de unión antiguos no puedan reutilizarse para una nueva reunión creada con el mismo ID de reunión. Es un mecanismo de seguridad importante que evita el acceso no autorizado mediante URL obsoletas.

Ambos endpoints quedaron obsoletos en BBB 2.4 y fueron eliminados en BBB 3.0. Han sido reemplazados por el parámetro clientSettingsOverride en la llamada create, que proporciona una forma más flexible de personalizar el comportamiento del cliente por reunión.