Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.
create – Створити зустріч
Кінцева точка create створює нову зустріч на сервері BigBlueButton. Якщо зустріч із таким самим meetingID уже існує, сервер повертає дані наявної зустрічі замість створення дубліката (ідемпотентна поведінка).
Ендпоінт
POST GET
https://api-guide.bbbserver.com/bigbluebutton/api/create?<parameters>&checksum=replace-with-checksum Обов’язкові параметри
| Параметр | Тип | Опис |
|---|---|---|
meetingID | String | Унікальний ідентифікатор зустрічі (від 2 до 256 символів, без ком). |
name | String | Відображувана назва зустрічі (від 2 до 256 символів). Обов’язково, починаючи з BBB 2.4. |
Необов’язкові параметри
Загальне
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
attendeePW Deprecated | String | (auto) | Пароль для доступу учасників. Застаріло з BBB 3.0 — генерується автоматично. |
moderatorPW Deprecated | String | (auto) | Пароль для доступу модератора. Застаріло з BBB 3.0 — генерується автоматично. |
welcome | String | — | Вітальне повідомлення, яке відображається в діалоговому вікні відомостей про сеанс. Підтримує заповнювачі: %%CONFNAME%%, %%DIALNUM%%, %%CONFNUM%%, %%SERVERURL%%. |
moderatorOnlyMessage | String | — | Повідомлення, яке відображається лише модераторам у діалоговому вікні відомостей про сеанс. |
dialNumber | String | — | Номер для підключення телефоном. |
voiceBridge | String | (auto) | П’ять випадкових цифр (може починатися з 0, наприклад 07382), генерується автоматично. Має бути унікальним для кожної зустрічі. |
maxParticipants | Number | 0 (unlimited) | Максимальна кількість учасників. На bbbserver.de це значення використовується для резервування місткості (див. примітки bbbserver.de нижче). |
duration | Number | 0 (unlimited) | Максимальна тривалість у хвилинах. У стандартному BBB зустріч автоматично завершується після закінчення часу. На bbbserver.de це використовується лише для планування місткості (див. примітки bbbserver.de нижче). |
logoutURL | String | — | URL, на який користувача буде перенаправлено після виходу. |
loginURL | String | — | URL, доступний користувачам під час зустрічі. BBB 3.0+ |
record | Boolean | false | Увімкнути запис медіа та подій. |
autoStartRecording | Boolean | false | Запис починається автоматично, коли приєднується перша особа. |
allowStartStopRecording | Boolean | true | Дозволити користувачам вручну запускати та зупиняти запис. |
recordFullDurationMedia | Boolean | false | Записувати медіа протягом усього часу зустрічі. BBB 2.6.9+ |
muteOnStart | Boolean | true | Вимикати мікрофон усім учасникам під час входу. |
guestPolicy | Enum | ALWAYS_ACCEPT | Політика гостей: ALWAYS_ACCEPT, ALWAYS_DENY або ASK_MODERATOR. |
webVoice Deprecated Removed in 4.0 | String | (= voiceBridge) | Застарілий параметр. Вибирав окрему голосову конференцію для старого Flash-клієнта й не має жодного ефекту починаючи з BBB 2.3; значення завжди замінюється на voiceBridge. |
meetingEndedURL | String | — | URL-адреса міжсерверного зворотного виклику, до якої звертаються після завершення зустрічі. На відміну від meta_endCallbackUrl, вона залишається на стороні сервера й не передається клієнту або до метаданих запису. Звернення здійснюється до URL-адреси без змін. BBB 2.2+ |
logoutTimer Undocumented Removed in 4.0 | Number | 0 (disabled) | Призначений для встановлення часу очікування у хвилинах до автоматичного виходу. Значення зберігається в bbb-web, але ніколи не надходить до клієнта, тому не має жодного ефекту. |
Макет і вигляд
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
meetingLayout | Enum | CUSTOM_LAYOUT | Макет за замовчуванням. Можливі значення: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY. |
logo | String | — | URL зображення логотипа, що відображається над списком учасників. BBB 2.4+ |
bannerText | String | — | Текст банера, що відображається в клієнті. BBB 2.0+ |
bannerColor | String | — | Колір фону банера у hex-форматі, наприклад #FF0000. BBB 2.0+ |
darklogo | String | — | URL зображення логотипа для темного режиму. BBB 3.0+ |
copyright Removed in 4.0 | String | — | Призначений для встановлення тексту повідомлення про авторські права в клієнті. Значення зберігається, але не передається клієнту, тому не має видимого ефекту. Щоб змінити текст повідомлення про авторські права, перевизначте public.app.copyright через clientSettingsOverride. |
Дозволи та налаштування блокування
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
webcamsOnlyForModerator | Boolean | false | Вебкамери видимі лише модераторам. |
allowModsToUnmuteUsers | Boolean | false | Дозволити модераторам вмикати звук іншим користувачам. BBB 2.2+ |
allowModsToEjectCameras | Boolean | false | Дозволити модераторам вимикати камери інших користувачів. BBB 2.4+ |
allowPromoteGuestToModerator | Boolean | false | Дозволити підвищення гостей до ролі модератора. BBB 2.7.9+ |
lockSettingsDisableCam | Boolean | false | Заблокувати доступ учасникам до поширення камери. BBB 2.2+ |
lockSettingsDisableMic | Boolean | false | Заблокувати мікрофон для учасників (лише прослуховування). BBB 2.2+ |
lockSettingsDisablePrivateChat | Boolean | false | Заблокувати приватний чат для учасників. BBB 2.2+ |
lockSettingsDisablePublicChat | Boolean | false | Заблокувати публічний чат для учасників. BBB 2.2+ |
lockSettingsDisableNotes | Boolean | false | Заблокувати спільні нотатки для учасників. BBB 2.5+ Псевдонім в однині lockSettingsDisableNote досі приймається, але є застарілим (видалено в BBB 4.0). |
lockSettingsHideUserList | Boolean | false | Приховати список учасників від глядачів. BBB 2.2+ |
lockSettingsHideViewersCursor | Boolean | false | Приховати курсори інших глядачів на дошці. BBB 2.5+ |
lockSettingsHideViewersAnnotation | Boolean | false | Приховати анотації інших глядачів на дошці. BBB 2.7+ |
lockSettingsLockOnJoin | Boolean | true | Застосовувати налаштування блокування одразу, коли користувач приєднується. BBB 2.2+ |
lockSettingsLockOnJoinConfigurable | Boolean | false | Увімкніть параметр lockSettingsLockOnJoin, щоб його можна було застосувати. BBB 2.2+ |
Вебкамера
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
userCameraCap | Number | 3 | Максимальна кількість одночасних вебкамер на одного користувача. BBB 2.4.5+ |
meetingCameraCap | Number | 0 (unlimited) | Максимальна кількість одночасних вебкамер у зустрічі. BBB 2.5+ |
maxPinnedCameras | Number | 3 | Максимальна кількість закріплених вебкамер. BBB 2.6+ |
Вимкнення функцій
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
disabledFeatures | String | — | Список функцій для вимкнення, розділений комами. BBB 2.5+ |
disabledFeaturesExclude | String | — | Список функцій для повторного ввімкнення для цієї зустрічі, розділений комами (перевизначає серверні значення за замовчуванням). BBB 2.6.9+ |
Доступні значення для disabledFeatures:
| Значення | Опис |
|---|---|
breakoutRooms | Сесійні кімнати |
captions Deprecated | Субтитри, введені вручну. Не має жодного ефекту починаючи з BBB 3.0 (введення субтитрів вручну перенесено до плагіна); використовуйте liveTranscription, щоб вимкнути автоматичну транскрипцію. |
chat | Публічний і приватний чат |
privateChat | Лише приватний чат |
deleteChatMessage | Видалення повідомлень чату BBB 3.0+ |
editChatMessage | Редагування повідомлень чату BBB 3.0+ |
replyChatMessage | Відповідь на повідомлення чату BBB 3.0+ |
chatMessageReactions | Реакції на повідомлення чату BBB 3.0+ |
chatEmojiPicker | Вибір емодзі в чаті BBB 3.0.9+ |
downloadPresentationWithAnnotations | Завантажити анотовану презентацію |
downloadPresentationConvertedToPdf | Завантажити конвертовану презентацію |
downloadPresentationOriginalFile | Завантажити оригінальний файл презентації |
snapshotOfCurrentSlide | Знімок поточного слайда |
externalVideos | Поширити зовнішнє відео |
importPresentationWithAnnotationsFromBreakoutRooms | Імпортувати презентацію з сесійних залів |
importSharedNotesFromBreakoutRooms | Імпортувати спільні нотатки з сесійних залів |
layouts Removed in 4.0 | Вибір макета (лише макет за замовчуванням) |
learningDashboard | Панель аналітики навчання |
learningDashboardDownloadSessionData | Завантажити дані сеансу панелі керування |
polls | Опитування |
screenshare | Спільний доступ до екрана |
sharedNotes | Спільні нотатки |
virtualBackgrounds | Віртуальні фони |
customVirtualBackgrounds | Завантажити власні віртуальні фони |
liveTranscription | Жива транскрипція |
presentation | Презентація |
cameraAsContent | Камера як вміст |
timer | Таймер |
infiniteWhiteboard | Безмежна дошка BBB 3.0+ |
raiseHand | Піднята рука BBB 3.0.7+ |
userReactions | Реакції користувачів BBB 3.0.8+ |
reactions | Реакції статусу емодзі (відрізняються від userReactions) BBB 2.7+ |
quizzes | Вікторини BBB 3.0.11+ |
plugins | Розширення BBB 3.0.25+ |
Життєвий цикл зустрічі
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
endWhenNoModerator | Boolean | false | Автоматично завершувати зустріч, якщо модератор відсутній. BBB 2.3+ |
endWhenNoModeratorDelayInMinutes | Number | 1 | Затримка в хвилинах перед автоматичним завершенням, якщо модератор відсутній. BBB 2.3+ |
meetingExpireIfNoUserJoinedInMinutes | Number | 5 | Завершити зустріч, якщо ніхто не приєднається протягом такої кількості хвилин. BBB 2.5+ |
meetingExpireWhenLastUserLeftInMinutes | Number | 1 | Завершити зустріч через X хвилин після виходу останнього користувача. 0 = вимкнено. BBB 2.5+ |
meetingKeepEvents | Boolean | false | Зберігати події, навіть якщо зустріч не записується. BBB 2.3+ |
learningDashboardCleanupDelayInMinutes | Number | 2 | Затримка перед видаленням панелі аналітики навчання. BBB 2.4+ |
allowRequestsWithoutSession | Boolean | false | Дозволити приєднання без cookie сеансу. BBB 2.4.3+ |
Презентація
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
preUploadedPresentation | String | — | URL файлу презентації для попереднього завантаження. BBB 2.7.2+ |
preUploadedPresentationName | String | — | Назва для попередньо завантаженої презентації. BBB 2.7.2+ |
preUploadedPresentationOverrideDefault | Boolean | true | Придушити стандартну презентацію (default.pdf). BBB 2.5+ |
maxNumPages | Number | 200 | Максимальна кількість сторінок на презентацію. BBB 3.0.2+ |
presentationUploadExternalUrl | String | — | URL зовнішнього застосунку вибору файлів. BBB 2.6+ |
presentationUploadExternalDescription | String | — | Опис зовнішнього застосунку завантаження. BBB 2.6+ |
presentationConversionCacheEnabled | Boolean | — | Увімкнути кеш презентації при використанні сховища S3. BBB 3.0.2+ |
Спільні нотатки
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
sharedNotesEditor Removed in 4.0 | String | etherpad | Редактор для спільних нотаток: blockNote або etherpad. Наведені нижче параметри початкового вмісту працюють лише з blockNote. BBB 3.0.25+ |
sharedNotesInitialContentJsonUrl | String | — | URL-адреса HTTPS, з якої завантажується початковий вміст спільних нотаток (документ BlockNote JSON). Розмір обмежено параметром maxSharedNotesInitialContentUrlPayloadSize (за замовчуванням 1024 КіБ), час очікування — 6 секунд; у разі перевищення обмежень нотатки залишаються порожніми без повідомлення про помилку. BBB 3.0.25+ |
sharedNotesInitialContentMarkdown | String | — | Необроблений Markdown, що використовується як початковий вміст спільних нотаток. sharedNotesInitialContentMarkdownUrl має пріоритет над цим значенням. BBB 3.0.33+ |
sharedNotesInitialContentMarkdownUrl | String | — | URL-адреса HTTPS, з якої завантажується Markdown для початкового вмісту спільних нотаток. Має пріоритет над параметром із безпосередньо заданим вмістом і модулем POST. BBB 3.0.33+ |
Запис
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
notifyRecordingIsOn | Boolean | false | Показувати модальне вікно для згоди на запис. BBB 2.6+ |
notifyRecordingAppend | String | — | Необов’язковий звичайний текст, що додається до діалогового вікна сповіщення про запис. Відображається лише з notifyRecordingIsOn=true; HTML відображається як текст. BBB 3.0.36+ |
Дошка
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
multiUserWhiteboardEnabled | Boolean | — | Автоматично надати доступ до дошки всім користувачам. За замовчуванням true у кімнатах для групової роботи. BBB 3.0.20+ |
Розширення
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
pluginManifests | JSON | — | Список маніфестів плагінів для сеансу. BBB 3.0+ |
pluginManifestsFetchUrl | String | — | URL-адреса файла JSON, що містить URL-адреси маніфестів плагінів. BBB 3.0.8+ |
Сесійні кімнати
Параметри isBreakout, parentMeetingID, sequence і freeJoin описують кімнату для групової роботи й використовуються лише під час створення самої кімнати (BigBlueButton виконує це внутрішньо). Інші параметри в цій таблиці задаються для батьківської зустрічі та застосовуються до її кімнат для групової роботи.
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
isBreakout | Boolean | — | Для кімнат для групової роботи має бути true. |
parentMeetingID | String | — | ID зустрічі батьківської зустрічі (обов’язково для сесійних кімнат). |
sequence | Number | — | Порядковий номер сесійної кімнати (обов’язково для сесійних кімнат). |
freeJoin | Boolean | — | Дозволити учасникам вільно обирати свою сесійну кімнату. |
breakoutRoomsPrivateChatEnabled | Boolean | true | Увімкнути приватний чат у сесійних кімнатах. |
breakoutRoomsRecord | Boolean | false | Записувати сесійні кімнати. |
breakoutRoomsCaptureSlides | Boolean | false | Захоплювати слайди із сесійних кімнат після їх завершення. |
breakoutRoomsCaptureNotes | Boolean | false | Захоплювати нотатки із сесійних кімнат після їх завершення. |
breakoutRoomsCaptureSlidesFilename | String | — | Ім’я файлу для захоплених слайдів. |
breakoutRoomsCaptureNotesFilename | String | — | Ім’я файлу для захоплених нотаток. |
groups | JSON | — | Попередньо визначені призначення груп у вигляді масиву JSON. |
Формат для groups:
[
{"id": "1", "name": "Group A", "roster": ["userId1", "userId2"]},
{"id": "2", "name": "Group B", "roster": ["userId3"]},
{"id": "3", "roster": []}
] Перевизначення налаштувань клієнта
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
allowOverrideClientSettingsOnCreateCall | Boolean | false | Серверне налаштування в bbb-web.properties (не параметр create), яке вмикає модуль clientSettingsOverride у тілі POST. BBB 3.0+ |
clientSettingsOverride | JSON | — | Перевизначає налаштування клієнта з settings.yml. Приймається лише як XML-модуль у тілі application/xml POST — не як параметр рядка запиту чи форми. BBB 3.0+ |
clientSettingsOverrideJsonUrl | String | — | URL-адреса файлу JSON із перевизначеннями налаштувань клієнта. Працює зі звичайними запитами GET, не потребує налаштувань на сервері та має пріоритет над модулем clientSettingsOverride. BBB 3.0.25+ |
Параметр clientSettingsOverride за замовчуванням вимкнений з міркувань безпеки. Його значення мають вищий пріоритет, ніж конфігурація на стороні сервера, а тіло POST не захищене checksum.
Приклад як XML у тілі POST:
<modules>
<module name="clientSettingsOverride">
<![CDATA[
{
"public": {
"app": {
"clientTitle": "My Conference",
"helpLink": "https://api-guide.bbbserver.com/help"
}
}
}
]]>
</module>
</modules> Мости
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
cameraBridge | String | bbb-webrtc-sfu | Медіаміст, що використовується для потоків із вебкамер: bbb-webrtc-sfu або livekit. BBB 3.0+ |
screenShareBridge | String | bbb-webrtc-sfu | Медіаміст, що використовується для демонстрації екрана: bbb-webrtc-sfu або livekit. BBB 3.0+ |
audioBridge | String | bbb-webrtc-sfu | Медіаміст, що використовується для аудіо: bbb-webrtc-sfu, livekit або freeswitch. BBB 3.0+ |
Ці параметри перевизначають загальносерверні налаштування мостів для окремої зустрічі.
Мета-параметри
Довільні метадані можна передавати як meta_<key>=<value>. Деякі мета-параметри мають особливе значення:
| Мета-параметр | Опис |
|---|---|
meta_endCallbackUrl | URL-адреса для зворотного виклику GET, коли зустріч завершується. Параметри: meetingID, recordingmarks. |
meta_bbb-recording-ready-url | URL-адреса для зворотного виклику POST, коли запис готовий (підписаний JWT). |
meta_analytics-callback-url | URL-адреса для зворотного виклику POST з аналітичними даними наприкінці зустрічі (JSON). |
meta_bbb-anonymize-chat | Анонімізувати відправників чату в записах (лише учасники). |
meta_bbb-anonymize-chat-moderators | Анонімізувати відправників чату в записах (включно з модераторами). |
Окрім параметрів meta_*, також підтримуються параметри plugin_*. Вони обробляються як метадані плагіна й можуть замінювати заповнювачі в URL маніфесту плагіна. BBB 3.0.10+
Приклад запиту
GET https://api-guide.bbbserver.com/bigbluebutton/api/create?name=Demo&meetingID=replace-with-meeting-id&attendeePW=replace-with-password&moderatorPW=replace-with-password&checksum=replace-with-checksum Приклад відповіді
<response>
<returncode>SUCCESS</returncode>
<meetingID>replace-with-meeting-id</meetingID>
<internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
<parentMeetingID>bbb-none</parentMeetingID>
<attendeePW>replace-with-password</attendeePW>
<moderatorPW>replace-with-password</moderatorPW>
<createTime>1715261728123</createTime>
<voiceBridge>70066</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
<hasUserJoined>false</hasUserJoined>
<duration>0</duration>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<messageKey></messageKey>
<message></message>
</response> Якщо зустріч з таким самим ID уже існує, відповідь містить попередження про дублікат:
<response>
<returncode>SUCCESS</returncode>
<meetingID>replace-with-meeting-id</meetingID>
<!-- ... same fields ... -->
<messageKey>duplicateWarning</messageKey>
<message>This conference was already in existence...</message>
</response> Завантаження презентацій через тіло POST
Презентації можна надсилати як тіло XML разом із запитом POST:
<modules>
<module name="presentation">
<document url="https://api-guide.bbbserver.com/files/slides.pdf" filename="slides.pdf"
downloadable="true" removable="false" current="true"/>
<document url="https://api-guide.bbbserver.com/files/extras.pdf" filename="extras.pdf"/>
<document name="inline.pdf">
JVBERi0xLjQK... (Base64-encoded content)
</document>
</module>
</modules> Атрибути для кожного елемента <document>:
| Атрибут | Тип | За замовчуванням | Опис |
|---|---|---|---|
url | String | — | URL зовнішнього файлу. |
filename | String | — | Ім’я файлу разом із розширенням. Обов’язкове, якщо шлях URL-адреси не закінчується іменем файлу з розширенням; інакше документ пропускається. |
name | String | — | Назва для документів, вбудованих у Base64. |
downloadable | Boolean | false | Дозволити користувачам завантажувати презентацію. |
removable | Boolean | true | Дозволити користувачам видаляти презентацію. |
current | Boolean | — | Ця презентація завантажується першою. |
Коли надано кілька документів, перший завантажується в клієнті, тоді як решта конвертуються у фоновому режимі.
bbbserver.de Примітки
Додатковий параметр
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
deactivateBbbserverDefaultChatTexts | Boolean | false | Якщо встановлено false (типово), bbbserver.de автоматично вставляє тексти чату (номери для дозвону, повідомлення про хостинг). Ваші власні тексти welcome і moderatorOnlyMessage додаються після них. Встановіть true, щоб приховати тексти bbbserver.de (white-labelling). |
Резервування місткості
На bbbserver.de параметри maxParticipants і duration мають особливе значення та поводяться інакше, ніж у стандартному BigBlueButton.
Під час створення зустрічі bbbserver.de резервує апаратну місткість:
- Указана кількість учасників гарантується й резервується на сервері на вказану тривалість.
- Зарезервована місткість віднімається з вашої заброньованої квоти одночасних підключень.
- Якщо не вказано, застосовуються значення за замовчуванням: 5 учасників і 60 хвилин (налаштовуються в панелі адміністратора в розділі Integrations & API → Integration API).
- Після завершення тривалості зустріч продовжує працювати, але місткість більше не резервується. bbbserver.de може автоматично завершити зустріч, якщо новій зустрічі знадобиться ця місткість.
- Параметр
durationне завершує зустрічі. На відміну від стандартного BBB, ви повинні надіслати API-викликend, щоб завершити зустріч через певний час.
Починаючи з BBB 3.0, параметри attendeePW і moderatorPW є застарілими. Натомість використовуйте параметр role у кінцевій точці join для призначення ролей.
Поширені запитання
duplicateWarning, який на це вказує.role у кінцевій точці join для призначення ролей учасника або модератора.modules/module із записами документів. Кожен документ може посилатися на зовнішню URL-адресу або містити дані файла в кодуванні Base64.meta_endCallbackUrl — це метапараметр, який може передаватися клієнту та до метаданих запису. meetingEndedURL — це серверний зворотний виклик, який залишається внутрішнім і не розкривається клієнтам, тому його рекомендовано використовувати для URL-адрес, що містять секретні токени.maxParticipants і duration. Зарезервовані слоти віднімаються з вашої квоти одночасних підключень. Після завершення тривалості зустріч триває, але більше не захищена від завершення, якщо місткість знадобиться в іншому місці.allowOverrideClientSettingsOnCreateCall у true і передавши clientSettingsOverride JSON у тілі POST. За замовчуванням це вимкнено з міркувань безпеки, оскільки тіло POST не охоплюється checksum.