Versión de la API: 4.x más reciente 3.x

Estás viendo la documentación de la API de BigBlueButton 3.x. La versión actual es BigBlueButton 4.x. ¿Planeas una actualización? La guía de migración enumera todos los cambios que necesitan tus llamadas a la API.

Capítulo 18

Metaparámetros y callbacks

Los metaparámetros son pares clave-valor libremente definibles que se pasan al crear una reunión. Le permiten adjuntar metadatos personalizados, activar devoluciones de llamada automatizadas en eventos específicos, controlar la anonimización de las grabaciones y documentar el origen de una reunión para integraciones de LMS.

Cómo funcionan los parámetros meta

Los parámetros meta se pasan en la llamada API create usando la convención de nombres meta_=. Puedes adjuntar cualquier número de parámetros meta a una sola reunión.

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Los parámetros meta se devuelven en las respuestas de getMeetingInfo y getRecordings.
  • Las grabaciones pueden filtrarse por valores meta usando getRecordings?meta_=.
  • Los metadatos de las grabaciones pueden actualizarse posteriormente mediante updateRecordings.

Parámetros meta de callback

Ciertos metaparámetros tienen un significado especial y activan devoluciones de llamada de HTTP cuando ocurren eventos específicos. Esto permite que su aplicación reaccione automáticamente a los eventos del ciclo de vida de la reunión.

meta_endCallbackUrl

Activa una solicitud HTTP GET a la URL especificada cuando finaliza la reunión.

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Propiedad Valor
Método HTTP GET
Activador Cuando finaliza la reunión
Parámetros de Callback meetingID — el identificador de la reunión
recordingmarks — true si la grabación contiene marcas, de lo contrario false

Ejemplo de solicitud de callback:

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Activa una solicitud HTTP POST cuando la grabación ha sido procesada y publicada por completo.

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Propiedad Valor
Método HTTP POST
Activador Cuando la grabación ha sido procesada por completo y publicada
Seguridad Los parámetros están firmados con JWT (JSON Web Token)
Cuerpo POST Contiene datos firmados con información de la grabación

No confunda esta devolución de llamada con endCallbackUrl. El procesamiento de la grabación puede llevar una cantidad considerable de tiempo después de que la reunión haya finalizado. La devolución de llamada recording-ready se activa solo una vez que el procesamiento ha concluido.

meta_analytics-callback-url

Activa una solicitud HTTP POST con datos analíticos agregados después de que finaliza la reunión.

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Propiedad Valor
Método HTTP POST
Activador Después de que finaliza la reunión (post-events hook)
Autenticación Token JWT enviado como encabezado Authorization: Bearer (HS512, firmado con el secreto compartido BBB, válido durante 24 horas)
Formato del cuerpo Objeto JSON que contiene version, meeting_id, internal_meeting_id, data
Contenido de los datos Duración de la participación, estadísticas de actividad, uso del chat y otros eventos agregados de la reunión

El callback de analítica solo se envía si se conservan los eventos de la reunión: pasa meetingKeepEvents=true en la llamada a create o configura defaultKeepEvents=true en el servidor (valor predeterminado: false). El esquema exacto del objeto de datos de analítica puede cambiar entre versiones.

Tenga en cuenta la diferencia en la entrega de JWT: analytics-callback-url envía el JWT como un encabezado HTTP Authorization, mientras que bbb-recording-ready-url incluye el JWT directamente en el cuerpo POST.

Parámetros de anonimización de grabaciones

Estos metaparámetros controlan si los nombres de los remitentes del chat se anonimizan en las grabaciones procesadas. Son útiles para el cumplimiento de la privacidad y los requisitos de protección de datos.

Parámetro Tipo Predeterminado Descripción
meta_bbb-anonymize-chat Boolean false Anonimiza los remitentes de mensajes del chat en las grabaciones procesadas. Solo afecta a los mensajes de los espectadores (no moderadores). Los nombres de los moderadores siguen siendo visibles.
meta_bbb-anonymize-chat-moderators Boolean false Además anonimiza a los remitentes de mensajes del chat de los moderadores en las grabaciones. Normalmente también requiere que se establezca meta_bbb-anonymize-chat=true.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

Los parámetros de anonimización solo se mencionan brevemente en la documentación oficial de la API. Su comportamiento se deriva del código fuente de BigBlueButton.

Parámetros de integración de LMS

Muchos plugins de LMS establecen automáticamente metaparámetros para documentar el origen de una reunión. Estos son informativos y no afectan el comportamiento de la reunión, pero son útiles para auditoría e informes.

Parámetro Ejemplo Descripción
meta_bbb-origin greenlight, moodle La aplicación de origen que creó la reunión.
meta_bbb-origin-version v3.1.0 Versión de la aplicación de origen.
meta_bbb-origin-server-name api-guide.bbbserver.com Nombre de host de la aplicación de origen.
meta_bbb-context Course: Computer Science Información de contexto como el nombre del curso.
meta_bbb-context-id course-42 Identificador de contexto para uso programático.

Buenas prácticas para metaparámetros personalizados

  • Use nombres de clave descriptivos (p. ej. meta_department, meta_project) que indiquen claramente el propósito del valor.
  • Codifique en URL los valores que contengan caracteres especiales, espacios o caracteres no ASCII.
  • Use metaparámetros para la integración con sistemas externos como CRMs, plataformas de aprendizaje o paneles de análisis.
  • Actualice los metadatos de la grabación posteriormente usando el endpoint updateRecordings para añadir o corregir metadatos.

Combine metaparámetros con el filtrado de getRecordings para crear potentes flujos de trabajo de búsqueda y categorización para sus grabaciones. Por ejemplo, filtre por meta_department=engineering para recuperar solo grabaciones de reuniones de ingeniería.

Preguntas frecuentes

No hay un límite estricto en la cantidad de metaparámetros. Sin embargo, dado que se pasan como parámetros de consulta de la URL, debe mantenerse dentro de límites prácticos de longitud de URL (normalmente entre 2.000 y 8.000 caracteres, según la configuración del servidor web).

Los metaparámetros establecidos durante la llamada create no pueden cambiarse mientras la reunión está en curso. Sin embargo, los metadatos de la grabación pueden actualizarse después del procesamiento mediante el endpoint updateRecordings.

El endCallbackUrl se activa inmediatamente cuando termina la reunión, usando una simple solicitud GET. El bbb-recording-ready-url se activa mucho más tarde, solo después de que la grabación haya sido procesada y publicada por completo, y usa una solicitud JWT POST firmada.

El cuerpo de la solicitud POST contiene un único campo de formulario signed_parameters que incluye un JWT firmado con HS256 mediante el secreto compartido del servidor. Su carga útil contiene meeting_id (el ID externo de la reunión) y record_id (el ID de la grabación).

La mayoría de los metaparámetros son puramente informativos y no cambian cómo funciona la reunión. Las excepciones son las URL de devolución de llamada, que activan solicitudes HTTP en eventos, y los parámetros de anonimización, que afectan cómo se procesan las grabaciones.

No. BigBlueButton convierte las claves de los parámetros de metadatos a minúsculas, por lo que meta_Department y meta_department hacen referencia a la misma clave y solo se conserva uno de los valores. Las claves se devuelven en minúsculas en las respuestas de getMeetingInfo y getRecordings. Los valores de los metadatos no se modifican.