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.
Resumen de la API
La API de BigBlueButton es una interfaz basada en HTTP que permite a aplicaciones externas —como sistemas de gestión del aprendizaje, portales web e integraciones personalizadas— crear, controlar y supervisar reuniones mediante programación. Todas las llamadas de API están protegidas mediante un mecanismo checksum basado en un shared secret.
Cómo funciona la API
La API de BBB sigue un modelo simple de solicitud-respuesta. Envías una solicitud HTTPS a un endpoint específico en tu servidor BigBlueButton, y el servidor responde con un documento XML que indica éxito o fallo.
- Protocolo: HTTPS (GET o POST)
- URL base:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Formato de respuesta: XML (con unas pocas excepciones que devuelven JSON)
- Autenticación: Shared-secret basada en checksum (sin OAuth, sin clave API)
Categorías de endpoints
Los endpoints de la API están organizados en las siguientes categorías:
| Categoría | Endpoints | Descripción |
|---|---|---|
| Administración | create, join, end | Crear, unirse y finalizar reuniones |
| Monitorizacion | isMeetingRunning, getMeetings, getMeetingInfo | Supervisar reuniones en ejecución |
| Grabaciones | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Gestionar grabaciones de reuniones |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Notificaciones de eventos en tiempo real |
| Mensajería | sendChatMessage | Enviar mensajes de chat BBB 3.0+ |
| Sesión | getJoinUrl | Gestión de sesiones BBB 3.0+ |
Métodos de HTTP
La mayoría de los endpoints aceptan solicitudes tanto GET como POST. Al usar POST, ten en cuenta que la checksum se calcula a partir de la query string de la URL, no del cuerpo de la solicitud. El cuerpo POST puede contener datos adicionales como XML de presentación o anulaciones de configuración del cliente.
Incluso al enviar una solicitud POST, la checksum debe calcularse a partir de los parámetros query string de la URL. El contenido del cuerpo no se incluye en el cálculo de checksum.
Formato de respuesta
Cada respuesta de la API contiene al menos los siguientes campos:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response> | Campo | Descripción |
|---|---|
returncode | Siempre SUCCESS o FAILED |
messageKey | Código de mensaje legible por máquina (presente en errores y advertencias, y en algunas respuestas correctas, como noMeetings o sentEndMeetingRequest) |
message | Descripción del error o advertencia legible por humanos |
Versionado de la API
La API de BigBlueButton no usa versionado tradicional basado en URL (sin rutas /v1/, /v2/). En su lugar, se añaden nuevos parámetros de forma retrocompatible, y los parámetros obsoletos se marcan en consecuencia pero no se eliminan de inmediato.
| Versión de BBB | Cambios destacados en la API |
|---|---|
| 2.2 | configuraciones de Lock, allowModsToUnmuteUsers |
| 2.4 | meetingLayout, allowModsToEjectCameras, role (join), Panel de aprendizaje |
| 2.5 | disabledFeatures, compatibilidad con SHA-384/SHA-512, webhook eventID filtro |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, paginación de grabaciones, modo oscuro |
| 2.7 | preUploadedPresentation (una sola URL) |
| 3.0 | sendChatMessage, getJoinUrl, pluginManifests, clientSettingsOverride |
Endpoints no documentados
Los siguientes endpoints existen en el código fuente de BigBlueButton, pero no forman parte de la API de integración. La documentación oficial describe stuns, signOut y learningDashboard únicamente como endpoints internos del cliente HTML5, autenticados con un sessionToken en lugar de una suma de comprobación; getSessions no está documentado en absoluto. Pueden cambiar sin previo aviso.
| Endpoint | Método | Descripción | Estado |
|---|---|---|---|
/api/stuns | GET POST | Devuelve la configuración del servidor STUN/TURN para conexiones WebRTC | Internal |
/api/signOut | GET POST | Finalizar sesión / cerrar sesión del usuario | Internal |
/api/getSessions | GET POST | Recuperar información de la sesión | Undocumented |
/api/learningDashboard | GET POST | Recuperar datos de analítica de aprendizaje | Internal |
Mutaciones de GraphQL (acciones dentro de la reunión)
Desde BBB 3.0, la mayoría de las acciones en tiempo real dentro de una reunión se manejan mediante mutaciones de GraphQL sobre WebSocket. Estas se usan internamente por el cliente HTML5 de BBB y no forman parte de la API clásica de REST.
| Categoría | Cantidad | Ejemplos |
|---|---|---|
| Chat | 11 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Gestión de usuarios | 28 | userSetMuted, userSetRole, userEjectFromMeeting |
| Presentación | 10 | presentationSetCurrent, presentationSetPage |
| Control de la reunión | 8 | meetingEnd, meetingRecordingSetStatus |
| Salas de grupos | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Encuestas | 5 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Temporizador | 8 | timerStart, timerStop, timerReset |
| Complementos | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
La capa GraphQL está pensada para uso interno del cliente y no proporciona una API pública estable. Las mutaciones y sus parámetros pueden cambiar entre versiones de BBB sin previo aviso.
Requisitos previos
Antes de empezar a usar la API de BigBlueButton, asegúrate de tener lo siguiente:
Un servidor BigBlueButton en funcionamiento (se recomienda la versión 3.0)
El secreto compartido (también llamado "security salt"), configurado en /etc/bigbluebutton/bbb-web.properties
Acceso HTTPS al servidor
Una aplicación del lado del servidor que genere las llamadas de API: el shared secret nunca debe exponerse en el lado del cliente
Nunca expongas shared secret en código del lado del cliente (JavaScript, aplicaciones móviles). Todas las llamadas de API deben generarse en el lado del servidor para evitar accesos no autorizados a tu servidor BigBlueButton.
Si estás usando bbbserver.de, consulta el capítulo específico de bbbserver.de IntegrationAPI para la configuración del panel, la compatibilidad de plugins y las diferencias con la API estándar.