Capítulo 4 GET

join – Unirse a la reunión

El endpoint join genera una URL que permite a un usuario entrar en una reunión BigBlueButton en curso. De forma predeterminada, el navegador redirige directamente al cliente BBB. Cuando redirect se establece en false, se devuelve una respuesta XML que contiene la URL de acceso y el token de sesión en su lugar.

Endpoint

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum

La llamada join es el único endpoint de API que se invoca directamente en el navegador del usuario final (como una URL de redirección). Todas las demás llamadas de API se realizan en el lado del servidor.

Parámetros obligatorios

Parámetro Tipo Descripción
meetingID String Obligatorio. El identificador de la reunión a la que se va a unir.
fullName String Obligatorio. El nombre para mostrar del usuario en la reunión.
role Enum Obligatorio. El rol del usuario: MODERATOR o VIEWER (sin distinguir entre mayúsculas y minúsculas). BBB 3.0+

Parámetros obsoletos

Parámetro Tipo Descripción
password String Obsoleto Obsoleto desde BBB 3.0. Asignación de roles mediante contraseña (attendeePW/moderatorPW de create). Sustituido por role.

Parámetros opcionales

Parámetro Tipo Predeterminado Descripción
createTime Number (Long) — Marca de tiempo de la respuesta de create. Evita unirse a una reunión que fue recreada después de que se generara la URL de acceso.
userID String — ID de usuario específico de la aplicación. Devuelto en getMeetingInfo y webhooks.
avatarURL String — URL de una imagen de avatar para el usuario.
webcamBackgroundURL String — URL de una imagen de fondo personalizada para la cámara web.
firstName String — Nombre (se usa para ordenar, no para mostrar).
lastName String — Apellido (se usa para ordenar, no para mostrar).
redirect Boolean true Cuando se establece en false, se devuelve una respuesta XML en lugar de una redirección del navegador.
errorRedirectUrl String — URL alternativa a la que redirigir en caso de errores (en lugar de la página de error predeterminada).
logoutURL String — URL a la que redirigir después de cerrar sesión. Sustituye el valor de create.
guest Boolean false Marcar al usuario como invitado. Sujeto a la guestPolicy de la reunión.
bot Boolean false Marcar al usuario como un agente automatizado.
excludeFromDashboard Boolean false Excluir al usuario del panel de analítica de aprendizaje.
enforceLayout Enum — Forzar una disposición específica para este usuario. Valores posibles: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Sin documentación La documentación oficial enumera incorrectamente este valor como PARTICIPANTS_CHAT_ONLY (sin _AND_).
auth Boolean (condicional) ‎⚠ Sin documentación Marcar al usuario como autenticado. Lógica condicional: si no se especifica guest, auth toma por defecto el valor true. Si se especifica guest=true, auth toma por defecto el valor false salvo que se establezca explícitamente.
defaultLayout String — ‎⚠ Sin documentación Disposición predeterminada para este usuario. Los mismos valores que meetingLayout en la llamada a create.
sessionName String — ‎⚠ Sin documentación Nombre de sesión personalizado. Solo surte efecto en combinación con existingUserID.
existingUserID String — ‎⚠ Sin documentación ID interno del usuario para volver a unirse o reconectarse con una sesión existente.
replaceSessionToken String — ‎⚠ Sin documentación Token de la sesión que se va a reemplazar (cuando se usa con existingUserID).

Parámetros de Userdata

Al llamar a join, puedes pasar datos personalizados como parámetros userdata-=. Estos se ponen a disposición en el cliente y pueden controlar el comportamiento de los complementos o la configuración del cliente por usuario.

Ciertas claves userdata pueden bloquearse en el lado del servidor mediante una lista de bloqueo (getJoinUrlUserdataBlocklist).

Ejemplo de solicitud

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum

Respuesta de ejemplo (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
    <meeting_id>replace-with-internal-meeting-id</meeting_id>
    <user_id>replace-with-user-id</user_id>
        <auth_token>replace-with-auth-token</auth_token>
        <session_token>replace-with-session-token</session_token>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?sessionToken=replace-with-session-token</url>
</response>

Respuestas de error

messageKey Significado
invalidMeetingIdentifier La reunión no existe.
meetingForciblyEnded La reunión fue finalizada por la fuerza.
maxParticipantsReached Se ha alcanzado el límite de participantes.
guestDeniedAccess Se denegó el acceso al invitado.
invalidPassword La contraseña no es válida.
checksumError El checksum no es válido.
mismatchCreateTimeParam El createTime no coincide con la reunión.
userNotFound No se encontró ningún usuario activo con este ID (al usar existingUserID).

Uso de createTime para la validación de URL de acceso

El parámetro createTime sirve como protección contra URL de acceso obsoletas:

Se crea una reunión y devuelve createTime: 1715261728123.

La URL de acceso se genera con createTime=1715261728123.

La reunión finaliza y se vuelve a crear con un nuevo createTime.

La URL de acceso antigua con el createTime anterior es rechazada.

Esto evita que los usuarios con enlaces de invitación desactualizados entren en una nueva reunión que reutiliza el mismo meetingID.

En bbbserver.de, la URL de acceso siempre se genera en el lado del servidor con la checksum y los parámetros correctos. No necesitas construir manualmente las URL de acceso.

Consejos de seguridad

Nunca expongas shared secret en el lado del cliente para calcular URL de acceso. Genera siempre las URL de acceso en el lado del servidor y pásalas al cliente.

  • La URL de acceso generada contiene checksum y solo debe usarse una vez.
  • Las URL de acceso deben generarse en el lado del servidor y pasarse al cliente.
  • Para reuniones sensibles, usa guest=true junto con guestPolicy=ASK_MODERATOR.

La transición de password a role es uno de los cambios incompatibles más importantes de BBB 3.0. Asegúrate de actualizar tu integración en consecuencia.

Preguntas frecuentes

En BBB 3.0 y posteriores, el parámetro role (MODERATOR o VIEWER) sustituye a la asignación de roles basada en contraseña utilizada en versiones anteriores. El parámetro password está obsoleto y ya no debe usarse en nuevas integraciones.

En lugar de redirigir el navegador a la reunión, el servidor devuelve una respuesta XML que contiene la URL de acceso y el token de sesión. Esto es útil para integraciones del lado del servidor que necesitan inspeccionar la respuesta o gestionar el token de sesión mediante programación.

Sí. Usa el parámetro existingUserID con el ID de usuario interno de la sesión anterior para volver a conectar. También puedes pasar replaceSessionToken para reemplazar la sesión anterior. Ten en cuenta que estos parámetros no están documentados y pueden cambiar sin previo aviso.

Cuando guest se establece en true, el usuario se marca como invitado y queda sujeto a la guestPolicy definida al crear la reunión. Por ejemplo, con ASK_MODERATOR, el moderador debe aprobar al invitado antes de que pueda entrar.

Los parámetros Userdata (userdata-=) te permiten pasar datos personalizados al cliente de la reunión por usuario. Pueden usarse para configurar el comportamiento del cliente, pasar información a complementos o personalizar la experiencia del usuario.

Este error se produce cuando el valor createTime de tu URL de acceso no coincide con el createTime de la reunión actualmente en curso. Esto suele ocurrir cuando una reunión se finalizó y se volvió a crear con el mismo meetingID, pero la URL de acceso aún contiene el createTime antiguo.