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 |
create?meetingID=demo&name=Demo
&lockSettingsDisableNote=true
&sharedNotesEditor=blockNote
©right=Example+Inc.
&meetingLayout=SMART_LAYOUTcreate?meetingID=demo&name=Demo
&lockSettingsDisableNotes=true
&clientSettingsOverrideJsonUrl=https%3A%2F%2F
example.com%2Fclient-settings.json
&meetingLayout=UNIFIED_LAYOUTDiseñ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.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoSi 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
meetingKeepEventsde su reunión principal (antes siempre usaban el valor predeterminado del servidordefaultKeepEvents). Las salas de grupos que crees por tu cuenta mediantecreateconisBreakout=truesiguen usando su propio parámetromeetingKeepEvents.
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. |
join?meetingID=demo&role=VIEWER
&fullName=<any length>
&enforceLayout=PRESENTATION_FOCUS
&userdata-bbb_change_layout=smartjoin?meetingID=demo&role=VIEWER
&fullName=<max. 255 characters>
&enforceLayout=UNIFIED_LAYOUT
&userdata-bbb_default_layout=UNIFIED_LAYOUTCambios en insertDocument
- Como máximo 10 documentos por llamada (
maxPresentationsPerRequest). Los documentos sobrantes se descartan; la respuesta sigue siendoSUCCESSconmessageKey=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
FAILEDahora incluye unmessageKey: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 conclientSettingsOverrideoclientSettingsOverrideJsonUrl. - 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/devuelven404con 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
200sin encabezadosAccess-Control-*(antes403);Vary: Originya no se envía. - Todas las respuestas incluyen los encabezados de seguridad
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyyX-XSS-Protection. Si incrustas respuestas de la API en marcos, revisaX-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
roleenjoin(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
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.sha(apiCallName + queryString + sharedSecret) con los mismos algoritmos hash compatibles.