Oglyad 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-ключа)
Категорії ендпоінтів
Ендпоінти API організовані в такі категорії:
| Категорія | Ендпоінти | Опис |
|---|---|---|
| Адміністрування | create, join, end | Створення, приєднання та завершення зустрічей |
| Monitoryng | 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. Вони використовуються внутрішньо клієнтом BBB HTML5 і не є частиною класичного 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 і не розглядається в цьому посібнику.