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.
bbbserver.de — IntegrationAPI
bbbserver.de es una plataforma de alojamiento prémium para BigBlueButton con sede en la UE y servidores ubicados en la UE. El IntegrationAPI es un proxy que replica por completo la API estándar de BBB: las aplicaciones externas se conectan mediante complementos BBB estándar y se comportan como si se comunicaran con un único servidor BBB. Entre bastidores, bbbserver distribuye automáticamente las conferencias entre varios servidores con capacidad suficiente.
Tu URL de API y shared secret están disponibles en el panel de administración de bbbserver en Customer Settings → IntegrationAPI. IntegrationAPI puede activarse o desactivarse desde allí.
Compatibilidad de Plugin
Las siguientes plataformas funcionan listas para usar; simplemente introduce la URL de API y shared secret:
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Diferencias con la API estándar
| Tema | Detalle |
|---|---|
maxParticipants / duration | Se utiliza para la reserva de capacidad, no solo como límites. Valores predeterminados cuando no se especifican: 5 participantes, 60 minutos. |
duration comportamiento | NO finaliza automáticamente las reuniones; se usa solo para la planificación de capacidad. |
| Parámetro adicional | deactivateBbbserverDefaultChatTexts — para fines de white-labeling. |
| Endpoints no disponibles | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Solo específico de la reunión, con ofuscación de privacidad. |
| Límites de tasa | Sin límites de tasa en IntegrationAPI. |
Además de IntegrationAPI, bbbserver.de ofrece una System API independiente con funciones específicas de la plataforma, como gestión de cuentas y estadísticas de uso. System API no es compatible con BBB y no se trata en esta guía.