Версія API: 4.x найновіша 3.x

Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.

Розділ 3 GET POST

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.
bannerText String — Текст банера, що відображається в клієнті. BBB 2.0+
bannerColor String — Колір фону банера у hex-форматі, наприклад #FF0000. BBB 2.0+

Дозволи та налаштування блокування

Параметр Тип За замовчуванням Опис
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, який на це вказує.

Ні. Починаючи з BBB 3.0, ці паролі є застарілими й генеруються автоматично. Використовуйте параметр role у кінцевій точці join для призначення ролей учасника або модератора.

Надішліть запит POST із тілом XML, що містить елемент modules/module із записами документів. Кожен документ може посилатися на зовнішню URL-адресу або містити дані файла в кодуванні Base64.

meta_endCallbackUrl — це метапараметр, який може передаватися клієнту та до метаданих запису. meetingEndedURL — це серверний зворотний виклик, який залишається внутрішнім і не розкривається клієнтам, тому його рекомендовано використовувати для URL-адрес, що містять секретні токени.

Коли ви створюєте зустріч, bbbserver.de резервує апаратну місткість на основі значень maxParticipants і duration. Зарезервовані слоти віднімаються з вашої квоти одночасних підключень. Після завершення тривалості зустріч триває, але більше не захищена від завершення, якщо місткість знадобиться в іншому місці.

Так, установивши allowOverrideClientSettingsOnCreateCall у true і передавши clientSettingsOverride JSON у тілі POST. За замовчуванням це вимкнено з міркувань безпеки, оскільки тіло POST не охоплюється checksum.
Посібник з API BigBlueButton