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, feedback | 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 error legible por máquina (solo presente en errores o advertencias) |
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 | logo, meetingLayout, allowModsToEjectCameras, Panel de aprendizaje |
| 2.5 | disabledFeatures, compatibilidad con SHA-384/SHA-512, webhook eventID filtro |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, modo oscuro |
| 2.7 | preUploadedPresentation (URL única), pagination de grabación |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role sustituye a password en join |
Endpoints no documentados
Los siguientes endpoints existen en el código fuente de BigBlueButton pero no están cubiertos en la documentación oficial. Se usan internamente y 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 | Undocumented |
/api/signOut | GET POST | Finalizar sesión / cerrar sesión del usuario | Undocumented |
/api/guestWait | GET | Consultar el estado de la sala de espera para invitados que esperan la aprobación del moderador | Undocumented |
/api/getSessions | GET POST | Recuperar información de la sesión | Undocumented |
/api/learningDashboard | GET POST | Recuperar datos de analítica de aprendizaje | Undocumented |
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 | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Gestión de usuarios | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Presentación | 11 | presentationSetCurrent, presentationSetPage |
| Control de la reunión | 8 | meetingEnd, meetingRecordingSetStatus |
| Salas de grupos | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Encuestas | 4 | 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.