Obzor API
API BigBlueButton — это интерфейс на основе HTTP, который позволяет внешним приложениям — таким как системы управления обучением, веб-порталы и пользовательские интеграции — программно создавать, управлять и отслеживать встречи. Все API-вызовы защищены с помощью механизма checksum, основанного на shared secret.
Как работает API
API BBB использует простую модель запрос-ответ. Вы отправляете запрос HTTPS к определённой конечной точке на вашем сервере BigBlueButton, а сервер отвечает документом XML, указывающим на успех или неудачу.
- Протокол: HTTPS (GET или POST)
- Базовый URL:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Формат ответа: XML (за несколькими исключениями, которые возвращают JSON)
- Аутентификация: Shared-secret-на основе checksum (без OAuth, без API-ключа)
Категории endpoint
Endpoint API организованы по следующим категориям:
| Категория | Endpoint | Описание |
|---|---|---|
| Администрация | create, join, end | Создание, присоединение и завершение встреч |
| Monitoring | isMeetingRunning, getMeetings, getMeetingInfo | Мониторинг активных встреч |
| Записи | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Управление записями встреч |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Уведомления о событиях в реальном времени |
| Сообщения | sendChatMessage | Отправка сообщений чата BBB 3.0+ |
| Сессия | getJoinUrl, feedback | Управление сессиями BBB 3.0+ |
Методы HTTP
Большинство конечных точек принимают как запросы GET, так и POST. При использовании POST обратите внимание, что checksum вычисляется по URL query string, а не по телу запроса. Тело POST может содержать дополнительные данные, такие как XML презентации или переопределения настроек клиента.
Даже при отправке запроса POST, checksum должен вычисляться из параметров query string в URL. Содержимое тела не включается в вычисление checksum.
Формат ответа
Каждый ответ API содержит как минимум следующие поля:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response>| Поле | Описание |
|---|---|
returncode | Всегда SUCCESS или FAILED |
messageKey | Машиночитаемый код ошибки (присутствует только при ошибках или предупреждениях) |
message | Человекочитаемое описание ошибки или предупреждения |
Версионирование API
API BigBlueButton не использует традиционное версионирование на основе URL (без путей /v1/, /v2/). Вместо этого новые параметры добавляются с сохранением обратной совместимости, а устаревшие параметры помечаются соответствующим образом, но не удаляются сразу.
| Версия BBB | Заметные изменения API |
|---|---|
| 2.2 | настройки Lock, allowModsToUnmuteUsers |
| 2.4 | logo, meetingLayout, allowModsToEjectCameras, Панель обучения |
| 2.5 | disabledFeatures, поддержка SHA-384/SHA-512, webhook eventID фильтр |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, темный режим |
| 2.7 | preUploadedPresentation (единый URL), запись pagination |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role заменяет password в join |
Недокументированные конечные точки
Следующие конечные точки существуют в исходном коде BigBlueButton, но не описаны в официальной документации. Они используются внутренне и могут изменяться без предупреждения.
| Конечная точка | Метод | Описание | Статус |
|---|---|---|---|
/api/stuns | GET POST | Возвращает конфигурацию сервера STUN/TURN для соединений WebRTC | Undocumented |
/api/signOut | GET POST | Завершить сеанс / выйти пользователю | Undocumented |
/api/guestWait | GET | Запросить статус лобби для гостей, ожидающих одобрения модератора | Undocumented |
/api/getSessions | GET POST | Получить информацию о сеансе | Undocumented |
/api/learningDashboard | GET POST | Получить данные аналитики обучения | Undocumented |
Мутации GraphQL (действия во время встречи)
Начиная с BBB 3.0, большинство действий в реальном времени внутри встречи обрабатываются через мутации GraphQL по WebSocket. Они используются внутренне HTML5-клиентом BBB и не являются частью классического API REST.
| Категория | Количество | Примеры |
|---|---|---|
| Чат | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Управление пользователями | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Презентация | 11 | presentationSetCurrent, presentationSetPage |
| Управление встречей | 8 | meetingEnd, meetingRecordingSetStatus |
| Сессионные комнаты | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Опросы | 4 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Таймер | 8 | timerStart, timerStop, timerReset |
| Плагины | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
Слой GraphQL предназначен для внутреннего использования клиентом и не предоставляет стабильный публичный API. Мутации и их параметры могут изменяться между версиями BBB без предупреждения.
Предварительные условия
Прежде чем начать использовать API BigBlueButton, убедитесь, что у вас есть следующее:
Работающий сервер BigBlueButton (рекомендуется версия 3.0)
Общий секрет (также называемый «security salt»), настроенный в /etc/bigbluebutton/bbb-web.properties
Доступ HTTPS к серверу
Серверное приложение, которое генерирует API-вызовы — shared secret никогда не должен раскрываться на стороне клиента
Никогда не раскрывайте shared secret в клиентском коде (JavaScript, мобильные приложения). Все API-вызовы должны генерироваться на стороне сервера, чтобы предотвратить несанкционированный доступ к вашему серверу BigBlueButton.
bbbserver.de — IntegrationAPI
bbbserver.de — это премиальная хостинговая платформа для BigBlueButton, расположенная в ЕС, с серверами в ЕС. IntegrationAPI — это прокси, полностью воспроизводящий стандартный API BBB — внешние приложения подключаются через стандартные плагины BBB и ведут себя так, как будто взаимодействуют с одним сервером BBB. За кулисами bbbserver автоматически распределяет конференции по нескольким серверам с достаточной ёмкостью.
Ваш API URL и shared secret доступны в панели администратора bbbserver в разделе Customer Settings → IntegrationAPI. IntegrationAPI можно включать и отключать там же.
Совместимость Plugin
Следующие платформы работают «из коробки» — просто введите API URL и shared secret:
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Отличия от стандартного API
| Тема | Подробность |
|---|---|
maxParticipants / duration | Используется для резервирования емкости, а не только как ограничения. Значения по умолчанию, если не указано: 5 участников, 60 минут. |
duration поведение | НЕ завершает встречи автоматически — используется только для планирования емкости. |
| Дополнительный параметр | deactivateBbbserverDefaultChatTexts — для целей white-labeling. |
| Недоступные эндпоинты | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Только для конкретной встречи, с обфускацией для защиты приватности. |
| Ограничения скорости | Нет ограничений по частоте запросов на IntegrationAPI. |
Помимо IntegrationAPI, bbbserver.de предлагает отдельный System API со специфическими для платформы функциями, такими как управление аккаунтами и статистика использования. System API не совместим с BBB и не рассматривается в этом руководстве.