Versión de la API: 4.x más reciente 3.x
Capítulo 2

Migrar de 3.x a 4.x

BigBlueButton 4.0 elimina varios parámetros y valores de diseño obsoletos, cambia diversos valores predeterminados e introduce nuevas claves de error. Esta guía enumera todo lo que debes comprobar en tus llamadas a la API cuando tu integración se comunica con un servidor BigBlueButton 4.x en lugar de un servidor BigBlueButton 3.x.

Alcance: Esta guía abarca los cambios en las llamadas a API realizadas por tu aplicación (create, join, insertDocument, …). No abarca la actualización ni la migración de los propios servidores de conferencias.

Primero, las buenas noticias: los endpoints, el cálculo de checksum, el formato de respuesta XML y todos los endpoints de grabación no han cambiado. La mayoría de las integraciones solo necesitan ajustar unos pocos parámetros. Los parámetros desconocidos o eliminados se ignoran sin aviso, por lo que un parámetro eliminado no provoca ningún error, pero tampoco tiene ya ningún efecto.

Resumen de todos los cambios

Endpoint Cambio Impacto Acción necesaria
create Se ha eliminado lockSettingsDisableNote (singular) Cambio incompatible Usa lockSettingsDisableNotes.
create El puente multimedia predeterminado ahora es livekit Cambio de comportamiento Comprueba el acceso telefónico con la sala de espera de invitados; establece audioBridge si es necesario.
create sharedNotesEditor se ignora: Etherpad se ha eliminado Cambio de comportamiento Elimina el parámetro; las notas compartidas siempre usan BlockNote.
create meetingEndedURL recibe meetingID y recordingmarks (4.0.1) Cambio de comportamiento Asegúrate de que tu controlador de llamadas de retorno admita los parámetros adicionales.
create Las salas de grupos creadas en el cliente heredan meetingKeepEvents de la reunión principal Cambio de comportamiento Normalmente, ninguna.
create El valor predeterminado de meetingLayout ahora es UNIFIED_LAYOUT Cambio de comportamiento Normalmente, ninguna; proporciona meetingLayout explícitamente para usar uno de los diseños especiales.
create Nuevas claves de error malformedXml y invalidPresentationUrl; la reunión no se crea Cambio de comportamiento Revisa la gestión de errores para los documentos cargados previamente.
create Se han eliminado layouts y captions de disabledFeatures Sin impacto funcional Elimina los valores de tu lista.
create Se han eliminado copyright, logoutTimer y webVoice Sin impacto funcional Elimina los parámetros (antes tampoco tenían efecto).
create, insertDocument Máx. 10 documentos por llamada (4.0.1) Cambio de comportamiento Gestiona documentsDropped o divide las cargas.
create, join Se han eliminado los diseños CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS y VIDEO_FOCUS Cambio de comportamiento Usa UNIFIED_LAYOUT o uno de los diseños especiales.
create, join Nuevos parámetros lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation Nuevo Opcional.
end También finaliza las salas de grupos creadas mediante la API Cambio de comportamiento Elimina las soluciones alternativas que finalizaban las salas isBreakout por separado.
insertDocument Límite de solicitudes y nuevas claves de error (4.0.1) Cambio de comportamiento Gestiona rateLimitExceeded y los nuevos valores de messageKey.
join fullName limitado a 255 caracteres Cambio incompatible Trunca los nombres; gestiona fullNameTooLong.
join webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction y userdata-bbb_parent_room_moderator eliminados Cambio de comportamiento Sustitúyelos como se describe a continuación.
sendChatMessage Nuevas claves de error para parámetros ausentes Cambio de comportamiento Gestiona missingParamMeetingID y missingParamMessage.
/api/rest/clientSettings Endpoint eliminado Cambio incompatible No vuelvas a llamarlo; usa clientSettingsOverride para personalizar la configuración del cliente.

Cambios en create

Parámetros eliminados

Parámetro (3.x) Estado en 4.x Reemplazo
lockSettingsDisableNote Eliminado (era un alias obsoleto). Cambio incompatible lockSettingsDisableNotes
sharedNotesEditor Se ignora. Etherpad se eliminó; todas las reuniones usan BlockNote. Ninguno. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown y sharedNotesInitialContentMarkdownUrl ahora funcionan en todas las reuniones, ya no solo con sharedNotesEditor=blockNote.
copyright Eliminado. El valor nunca se pasaba al cliente. Ajuste del cliente public.app.copyright mediante clientSettingsOverride (requiere allowOverrideClientSettingsOnCreateCall=true en el servidor) o clientSettingsOverrideJsonUrl.
logoutTimer Eliminado. El valor nunca se pasaba al cliente. —
webVoice Eliminado. Obsoleto desde que se retiró el cliente Flash en BBB 2.3. voiceBridge
Antes (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
Después (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Diseños

La selección de diseños en el cliente se sustituyó por un único diseño adaptable. UNIFIED_LAYOUT es el nuevo valor predeterminado de meetingLayout, y los diseños clásicos ya no se aceptan en meetingLayout (en create), enforceLayout (en join y getJoinUrl) ni userdata-bbb_default_layout:

Los valores de diseño eliminados no provocan un error: el cliente los ignora y recurre a la siguiente fuente de diseño (por ejemplo, el diseño de la reunión o el diseño predeterminado).

Valor en 3.x Estado en 4.x Valor recomendado en 4.x
CUSTOM_LAYOUT (predeterminado en 3.x) Eliminado UNIFIED_LAYOUT
SMART_LAYOUT Eliminado UNIFIED_LAYOUT
PRESENTATION_FOCUS Eliminado UNIFIED_LAYOUT; para una pantalla que solo muestre la presentación (por ejemplo, un proyector), PRESENTATION_ONLY
VIDEO_FOCUS Eliminado UNIFIED_LAYOUT; para un mosaico de cámaras, CAMERAS_ONLY
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY Sin cambios —

CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY y MEDIA_ONLY son diseños especiales para escenarios híbridos o de quiosco: ocultan gran parte de la interfaz de usuario. No los uses como sustitutos directos de los diseños eliminados en reuniones normales.

Puentes multimedia

audioBridge, cameraBridge y screenShareBridge ahora tienen como valor predeterminado livekit en lugar de bbb-webrtc-sfu. El valor freeswitch ya no es válido para audioBridge: el cliente lo trata como un puente desconocido y ahora recurre a livekit (antes, bbb-webrtc-sfu). Usa audioBridge=bbb-webrtc-sfu en su lugar.

Los participantes que se conectan por teléfono al puente de audio LiveKit omiten la sala de espera para invitados, incluso con guestPolicy=ASK_MODERATOR. Si tu integración depende de que los moderadores admitan a los participantes telefónicos, pasa audioBridge=bbb-webrtc-sfu en create, lo que cambia el puente de audio a FreeSWITCH.

Nota para los clientes de bbbserver.de: estamos trabajando para mantener la restricción de acceso telefónico de BigBlueButton también al usar LiveKit.

Los parámetros de userdata, userdata-bbb_listen_only_mode y userdata-bbb_transparent_listen_only, solo se evalúan con audioBridge=bbb-webrtc-sfu. Con livekit, los usuarios en modo de solo escucha siempre se conectan mediante una conexión de micrófono silenciada.

Valores de disabledFeatures

Valor Cambio
layouts Ya no es válido: la selección de diseños se eliminó del cliente. Sin impacto funcional
captions Ya no es válido: no tenía efecto desde BBB 3.0. Usa liveTranscription para desactivar la transcripción automática. Sin impacto funcional
pinChatMessage Nuevo: desactiva la fijación de mensajes del chat. Nuevo
multiFunctionalMode Nuevo: desactiva el panel lateral auxiliar. Nuevo
webcamGrid Nuevo: desactiva los recuadros de avatar de los usuarios sin cámara mientras la presentación está minimizada. Nuevo

Presentaciones cargadas previamente

Desde BBB 4.0.1, una llamada a create carga como máximo 10 documentos (ajuste del servidor maxPresentationsPerRequest; la presentación predeterminada no se cuenta). El documento marcado como current="true" siempre se conserva; los demás se procesan en el orden de la solicitud. Los documentos que exceden el límite se descartan, pero la reunión se crea de todos modos y la respuesta contiene messageKey=documentsDropped:

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>demo</meetingID>
  <!-- ... -->
  <messageKey>documentsDropped</messageKey>
  <message>...</message>
</response>

Ten en cuenta que messageKey ahora puede ser documentsDropped en SUCCESS. Si tu código trata cualquier messageKey como un error o solo comprueba duplicateWarning, ajústalo. Sube documentos adicionales después con insertDocument.

Además, create ahora comprueba el cuerpo de la solicitud antes de crear la reunión: un cuerpo que no sea XML bien formado produce un error messageKey=malformedXml, y una URL de documento con sintaxis no válida produce un error messageKey=invalidPresentationUrl. En ambos casos, la reunión no se crea.

Callback de finalización de la reunión

Desde BBB 4.0.1, el callback meetingEndedURL añade meetingID y recordingmarks a la cadena de consulta de tu URL (4.0.0 llamaba a la URL sin modificarla). Los parámetros existentes conservan sus valores, pero pueden volver a codificarse. Si tu URL ya contiene un parámetro con el mismo nombre, se envían ambos valores, primero el tuyo.

Callback (3.x)
GET https://example.com/ended?token=a817dde5
Callback (4.0.1+)
GET https://example.com/ended?token=a817dde5
  &recordingmarks=true&meetingID=demo

Si todavía usas meta_endCallbackUrl: la documentación oficial ahora recomienda meetingEndedURL en su lugar, porque los valores de meta_* pueden quedar expuestos a los usuarios de la reunión y podrían filtrar tokens secretos incluidos en la URL del callback. No verifiques una firma sobre la cadena de consulta sin procesar, ya que esta puede volver a codificarse.

Otros cambios

  • Las salas de grupos creadas en el cliente ahora heredan el valor efectivo de meetingKeepEvents de su reunión principal (antes siempre usaban el valor predeterminado del servidor defaultKeepEvents). Las salas de grupos que crees por tu cuenta mediante create con isBreakout=true siguen usando su propio parámetro meetingKeepEvents.

Nuevos parámetros

Parámetro Predeterminado Descripción
lockSettingsPresenterPolicy requireApproval Política de «Solicitar ser presentador»: moderatorOnly, requireApproval o freeForAll.
requireUserConsentBeforeUnmuting false Con true, los usuarios deben dar su consentimiento antes de que un moderador les active el micrófono (solo es relevante con allowModsToUnmuteUsers=true).

El valor predeterminado requireApproval significa que los espectadores ahora pueden solicitar el rol de presentador en el cliente. Si solo los moderadores deben asignar el rol de presentador, pasa lockSettingsPresenterPolicy=moderatorOnly.

Todos los detalles: Crear reunión (4.x).

Cambios en join

Parámetro Cambio Qué hacer
fullName Limitado a 255 caracteres. Los valores más largos se rechazan con fullNameTooLong (antes no había límite). Trunca los nombres para mostrar antes de construir la URL para unirse.
enforceLayout Solo se aceptan UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY y MEDIA_ONLY. Convierte los valores antiguos según la tabla de diseños anterior.
webVoiceConf Eliminado (el valor nunca se leía). Elimina el parámetro.
userdata-bbb_change_layout Eliminado; sus valores smart, videoFocus, presentationFocus y custom ya no existen. Usa userdata-bbb_default_layout.
userdata-enable-user-reaction Eliminado. Usa disabledFeatures=userReactions en create o la opción de configuración del cliente public.userReaction.enabled.
userdata-bbb_parent_room_moderator Eliminado en 4.0.1; no tenía ningún efecto desde 3.0.25. Asigna el rol en la sala de grupos con role.
userdata-bbb_hide_sidebar_navigation Nuevo: cierra la navegación lateral y el panel lateral al unirse. Nuevo Opcional.
Antes (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Después (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Cambios en insertDocument

  • Como máximo 10 documentos por llamada (maxPresentationsPerRequest). Los documentos sobrantes se descartan; la respuesta sigue siendo SUCCESS con messageKey=documentsDropped.
  • Límite de llamadas por reunión: de forma predeterminada, 30 llamadas cada 60 segundos. Las llamadas que superan el límite fallan con rateLimitExceeded; vuelve a intentarlo tras una espera.
  • Cada respuesta FAILED ahora incluye un messageKey: notFound, malformedXml, invalidPresentationUrl, invalidFilename, presentationDisabled, noDocuments.

Si tu gestión de errores compara el texto de message, pasa a usar messageKey. Detalles: Insertar presentación (4.x).

Cambios en end

Al finalizar una reunión, ahora también finalizan todas sus salas de grupos, incluidas las creadas mediante create con isBreakout=true. Antes, solo las salas de grupos creadas desde el cliente finalizaban junto con su reunión principal. Si tu aplicación finalizaba esas salas con llamadas independientes a end, esas llamadas ya no son necesarias; asegúrate de que tu código tolere que una sala de grupos ya haya finalizado.

Cambios en sendChatMessage

El messageKey para los parámetros ausentes ha cambiado: si falta message, ahora se devuelve missingParamMessage (antes nullError); si falta meetingID, se devuelve missingParamMeetingID (antes meetingNotFound). Las infracciones de longitud siguen devolviendo sizeError, y los caracteres no válidos en meetingID siguen devolviendo validationError.

Endpoints eliminados y cambios a nivel de HTTP

  • Se ha eliminado /api/rest/clientSettings. La configuración del cliente ahora se entrega mediante GraphQL dentro del cliente; personalízala para cada reunión con clientSettingsOverride o clientSettingsOverrideJsonUrl.
  • Se han eliminado las partes de la API GraphQL relacionadas con Etherpad. Los complementos o las integraciones que las consulten reciben un error de validación.
  • Las URL desconocidas bajo /bigbluebutton/ devuelven 404 con un cuerpo JSON en lugar de un documento XML.
  • Las solicitudes con más de 10,000 parámetros reciben una respuesta HTTP 500.
  • Las solicitudes de verificación previa de CORS sin configuración de CORS devuelven 200 sin encabezados Access-Control-* (antes 403); Vary: Origin ya no se envía.
  • Todas las respuestas incluyen los encabezados de seguridad X-Frame-Options, X-Content-Type-Options, Referrer-Policy y X-XSS-Protection. Si incrustas respuestas de la API en marcos, revisa X-Frame-Options.

Los cambios en las respuestas 404, el límite de parámetros y las solicitudes de verificación previa de CORS ya se aplican desde BBB 3.0.40 (bbb-web en Grails 8); solo te afectan si tus servidores ejecutan una versión 3.0 anterior. Los encabezados de seguridad son nuevos en 4.0; en BBB 3.0.40 están desactivados.

Sin cambios

Las siguientes partes de la API son idénticas en 3.x y 4.x; no se necesitan cambios:

  • Cálculo de Checksum y algoritmos hash compatibles (SHA-1, SHA-256, SHA-384, SHA-512)
  • isMeetingRunning, getMeetings, getMeetingInfo (Parámetros y formato de respuesta)
  • getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack
  • Webhooks, salvo el evento pad-content, que ya no existe porque se ha eliminado Etherpad
  • Asignación de roles mediante role en join (introducida en BBB 2.4)

Opciones de configuración del servidor que afectan al comportamiento de la API

El operador del servidor configura estas opciones en bbb-web.properties, no mediante parámetros de la API. Si gestionas tus propios servidores o tu proveedor cambia estas opciones, el comportamiento de tus llamadas a la API puede cambiar:

Ajuste Cambio en 4.x
allowDuplicateExtUserid Eliminado. Ahora, userID controla las conexiones múltiples con el mismo maxUserConcurrentAccesses.
defaultMeetingLayout Valor predeterminado: UNIFIED_LAYOUT (antes CUSTOM_LAYOUT).
audioBridge, cameraBridge, screenShareBridge Valor predeterminado: livekit.
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec Nuevos límites (valores predeterminados: 10, 30, 60).
accessControlAllowOrigin Eliminado; CORS se configura mediante grails.cors.*.

Lista de comprobación para la migración

Busca en tu código los valores eliminados: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction y clientSettings.

Limpia disabledFeatures: elimina layouts y captions.

Limita los nombres para mostrar a 255 caracteres y gestiona fullNameTooLong.

Comprueba las cargas de presentaciones: no más de 10 documentos por llamada a create/insertDocument; gestiona documentsDropped y rateLimitExceeded.

Revisa tu controlador de callbacks para meetingEndedURL: debe aceptar los parámetros adicionales meetingID y recordingmarks.

Decide los nuevos valores predeterminados: las solicitudes de presentador (lockSettingsPresenterPolicy) y la sala de espera de invitados para los participantes por teléfono (audioBridge).

Haz pruebas con un servidor 4.x, en particular con las salas de grupos, las cargas de presentaciones y tu gestión de errores basada en messageKey.

¿Tu integración debe admitir ambas versiones durante un tiempo? Todos los cambios anteriores son compatibles con versiones anteriores en un sentido: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout y los nombres para mostrar de un máximo de 255 caracteres también funcionan en servidores BBB 3.0.19+. Úsalos en todas partes y tus llamadas a la API funcionarán en ambas versiones.

¿Buscas la documentación anterior? La referencia completa de 3.x sigue disponible, por ejemplo, Crear reunión (3.x).

Preguntas frecuentes

Puedes —y deberías— hacerlo de antemano. UNIFIED_LAYOUT, lockSettingsDisableNotes y userdata-bbb_default_layout son las alternativas recomendadas y ya son compatibles con BBB 3.0.19. Prepara tu código para que la actualización del servidor no requiera publicar simultáneamente una nueva versión de tu aplicación.

No. BigBlueButton ignora los parámetros desconocidos, por lo que un parámetro eliminado no tiene ningún efecto ni genera avisos. Por eso es fácil pasar por alto los parámetros eliminados: comprueba tu código con las listas de esta guía.

No. checksum se sigue calculando como sha(apiCallName + queryString + sharedSecret) con los mismos algoritmos hash compatibles.

No. Esta guía solo cubre los cambios en las llamadas a API que realiza tu aplicación. La actualización de los propios servidores de conferencias es un tema aparte y corresponde al operador de tu servidor.