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

La URL de devolución de llamada analítica proviene del código fuente de BigBlueButton y no está completamente documentada en la documentación oficial de la API. El esquema exacto del objeto de datos analíticos no está estandarizado y puede cambiar entre versiones. undocumented

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. undocumented

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.

Los detalles de la firma JWT no están completamente especificados en la documentación oficial. Según el código fuente de BigBlueButton, el JWT se firma usando el secreto compartido del servidor. Las claims exactas y el algoritmo deben verificarse con su versión específica de BigBlueButton.

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.

Sí. Las claves de los metaparámetros se tratan como cadenas sensibles a mayúsculas y minúsculas. Por ejemplo, meta_Department y meta_department se almacenarían como dos parámetros separados. Use una capitalización coherente en su integración para evitar duplicados.