Capítulo 7 GET POST

getJoinUrl – Generar URL de acceso

El endpoint getJoinUrl genera una nueva URL de acceso para un usuario que ya se ha unido a una reunión. Esto permite que el mismo usuario abra sesiones adicionales —por ejemplo en una segunda pantalla o tras cambiar de dispositivo— sin volver a autenticarse mediante el flujo estándar de join. BBB 3.0+

Endpoint

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

Este endpoint usa autenticación session-token en lugar del mecanismo estándar de suma de verificación shared-secret. El usuario ya debe haberse unido mediante el endpoint join y disponer de un sessionToken válido.

Este es el único endpoint de API de BigBlueButton que devuelve JSON en lugar de XML.

Parámetros obligatorios

Parámetro Tipo Obligatorio Predeterminado Descripción
sessionToken String Sí — El sessionToken del usuario para el que debe generarse una nueva URL de acceso.

Parámetros opcionales

Parámetro Tipo Obligatorio Predeterminado Descripción
replaceSession Boolean No false Cuando se establece en true, la sesión original se invalida y se reemplaza por la nueva (transferencia de sesión).
sessionName String No — Un nombre descriptivo para la nueva sesión.
enforceLayout String No — Sobrescribe el diseño de la nueva sesión.
userdata-* ↗ undocumented String No — Datos de usuario personalizados para la nueva sesión. Las claves deben tener el prefijo userdata-.

Casos de uso

  • Escenarios híbridos — un moderador usa una pantalla para la presentación y una segunda pantalla para la vista de participantes.
  • Cambio de dispositivo — un usuario pasa de su equipo de escritorio a una tableta durante una reunión.
  • Configuraciones de varias pantallas — una sala de conferencias con varias pantallas que muestran diferentes diseños.

Comportamiento

La nueva sesión comparte la identidad del usuario con la sesión original. El usuario aparece solo una vez en la lista de participantes.

Sin replaceSession, ambas sesiones existen en paralelo.

Con replaceSession=true, la sesión original se invalida y el usuario se transfiere sin interrupciones a la nueva sesión.

Ejemplo de solicitud

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Respuesta de ejemplo (éxito)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
        "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Respuestas de error

Cuando una solicitud falla, el endpoint devuelve un objeto JSON con un mensaje de error descriptivo: 

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>",
        "sessionToken": "replace-with-session-token"
  }
}
Mensaje Significado
Invalid Session El sessionToken no es válido o ha expirado.
Access denied No se encontró al usuario o no tiene permiso.
Meeting not found La reunión no existe o ya no está en ejecución.

Lista de bloqueo de Userdata

Al usar parámetros userdata-* con getJoinUrl, una lista de bloqueo configurable (getJoinUrlUserdataBlocklist) restringe ciertas claves userdata para usuarios no moderadores:

  • Si la lista de bloqueo contiene el valor "all", se bloquean todos los parámetros userdata para los espectadores.
  • Los moderadores omiten la lista de bloqueo, excepto en breakout rooms.
  • El parámetro enforceLayout siempre está permitido, independientemente de la lista de bloqueo.

El endpoint solo está disponible cuando el usuario ya dispone de un sessionToken válido; es decir, primero debe haberse unido a la reunión mediante el endpoint estándar join. Los tokens expirados se rechazan.

Notas para usuarios de bbbserver.de

El endpoint getJoinUrl está disponible en todas las instancias de bbbserver.de que ejecuten BigBlueButton 3.0 o posterior. Si tu integración necesita admitir escenarios de varias pantallas o cambio de dispositivo, este endpoint proporciona una forma limpia de generar URL de acceso adicionales sin requerir una segunda llamada join con credenciales de moderador.

Para casos de uso de cambio de dispositivo, establezca replaceSession=true para transferir la sesión sin interrupciones al nuevo dispositivo. Esto evita que quede una sesión obsoleta en el dispositivo anterior que podría causar confusión en la lista de participantes.

Preguntas frecuentes

No. A diferencia de la mayoría de los endpoints de API de BigBlueButton, getJoinUrl usa autenticación session-token. Pasas el parámetro sessionToken en lugar de calcular una suma de verificación con el secreto compartido.

No. El usuario ya debe haberse unido mediante el endpoint estándar join y disponer de un sessionToken válido y activo. El endpoint no puede usarse para crear URL de acceso iniciales.

Ambas sesiones —la original y la nueva— existirán en paralelo. El usuario aparece solo una vez en la lista de participantes, pero ambas ventanas del navegador o dispositivos permanecen activos.

Esta es una decisión de diseño tomada por los desarrolladores de BigBlueButton al introducir este endpoint en la versión 3.0. Es el único endpoint de API que devuelve JSON. Todos los demás endpoints siguen devolviendo XML.

El endpoint getJoinUrl se introdujo en BigBlueButton 3.0. No está disponible en versiones anteriores.

No necesariamente. Una lista de bloqueo configurable puede restringir ciertas claves userdata para usuarios no moderadores. Si la lista de bloqueo se establece en "all", no se transfieren parámetros userdata para los espectadores. Los moderadores omiten la lista de bloqueo excepto en breakout rooms.