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

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

Розділ 4 GET

join – Приєднатися до зустрічі

Кінцева точка join генерує URL-адресу, яка дозволяє користувачеві увійти до активної зустрічі BigBlueButton. За замовчуванням браузер перенаправляється безпосередньо до клієнта BBB. Якщо redirect встановлено в false, натомість повертається відповідь XML, що містить URL приєднання та токен сесії.

Ендпоінт

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum

Виклик join — це єдина кінцева точка API, захищена контрольною сумою, яка викликається безпосередньо в браузері кінцевого користувача (як URL-адреса перенаправлення). Усі інші виклики API, захищені контрольною сумою, виконуються на стороні сервера.

Обов’язкові параметри

Параметр Тип Опис
meetingID String Обов’язково. Ідентифікатор зустрічі, до якої потрібно приєднатися.
fullName String Обов’язково. Ім’я користувача, яке відображається на зустрічі.
role Enum Обов’язково. Роль користувача: MODERATOR або VIEWER (без урахування регістру). BBB 2.4+

Застарілі параметри

Параметр Тип Опис
password String Застаріло Застаріло з BBB 3.0. Призначення ролей через пароль (attendeePW/moderatorPW з create). Замінено на role.
webVoiceConf String Застаріло Removed in 4.0 Власний додатковий номер для голосового зв’язку в старому клієнті Flash. Значення не обробляється й не має жодного ефекту.

Необов’язкові параметри

Параметр Тип За замовчуванням Опис
createTime Number (Long) — Мітка часу з відповіді create. Запобігає входу до зустрічі, яку було повторно створено після генерування URL-адреси входу.
userID String — Специфічний для застосунку ідентифікатор користувача. Повертається в getMeetingInfo і webhooks.
avatarURL String — URL-адреса зображення аватара користувача.
webcamBackgroundURL String — URL-адреса власного фонового зображення для вебкамери.
firstName String — Ім’я (використовується для сортування, не для відображення).
lastName String — Прізвище (використовується для сортування, не для відображення).
redirect Boolean true Якщо встановлено false, замість перенаправлення браузера повертається відповідь XML.
errorRedirectUrl String — Альтернативна URL-адреса для перенаправлення у разі помилок (замість стандартної сторінки помилки).
logoutURL String — URL-адреса для перенаправлення після виходу. Перевизначає значення з create.
guest Boolean false Позначити користувача як гостя. Підпорядковується політиці guestPolicy цієї зустрічі.
bot Boolean false Позначити користувача як автоматизованого агента.
excludeFromDashboard Boolean false Виключити користувача з панелі аналітики навчання.
enforceLayout Enum — Примусово встановити певний макет для цього користувача. Можливі значення: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
auth Boolean (умовно) ‎⚠ Не задокументовано Позначити користувача як автентифікованого. Умовна логіка: якщо guest не вказано, auth за замовчуванням має значення true. Якщо guest вказано (з будь-яким значенням, зокрема false), auth за замовчуванням має значення false, якщо його не задано явно.
defaultLayout String — ‎⚠ Не задокументовано Вилучено з офіційного API в BBB 3.0. Сервер усе ще приймає це значення, але ніколи його не обробляє, тому воно не має жодного ефекту. Використовуйте userdata-bbb_default_layout, щоб задати початковий макет клієнта.
sessionName String — ‎⚠ Не задокументовано Власна назва сесії. Працює лише в поєднанні з existingUserID.
existingUserID String — ‎⚠ Не задокументовано Внутрішній ідентифікатор користувача для повторного входу або перепідключення до наявної сесії.
replaceSessionToken String — ‎⚠ Не задокументовано Токен сесії, яку потрібно замінити (коли використовується разом із existingUserID).

Параметри Userdata

Під час виклику join ви можете передавати користувацькі дані як параметри userdata-=. Вони стають доступними в клієнті та можуть керувати поведінкою плагінів або налаштуваннями клієнта для кожного користувача окремо.

Серверний список блокування getJoinUrlUserdataBlocklist застосовується лише до URL-адрес приєднання, згенерованих через getJoinUrl. Сам виклик join приймає всі ключі userdata.

Частина після userdata- не повинна містити ще одного дефіса, інакше параметр буде відкинуто. Префікс userdata-bbb_ зарезервовано для BigBlueButton — використовуйте власний префікс для даних інтеграції (наприклад, userdata-myapp_cohort). Повний список доступний у розділі Налаштування клієнта.

Приклад запиту

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum

Приклад відповіді (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
  <meeting_id>replace-with-internal-meeting-id</meeting_id>
  <user_id>replace-with-user-id</user_id>
  <auth_token>replace-with-auth-token</auth_token>
  <session_token>replace-with-session-token</session_token>
  <guestStatus>ALLOW</guestStatus>
  <url>https://api-guide.bbbserver.com/html5client/?sessionToken=replace-with-session-token</url>
</response>

Відповіді з помилками

messageKey Значення
invalidMeetingIdentifier Зустріч не існує.
meetingForciblyEnded Зустріч було примусово завершено.
maxParticipantsReached Досягнуто ліміту учасників.
guestDeniedAccess Гостю було відмовлено в доступі.
invalidPassword Пароль недійсний.
checksumError checksum недійсний.
mismatchCreateTimeParam createTime не відповідає зустрічі.
userNotFound Не знайдено активного користувача з цим ID (під час використання existingUserID).

Використання createTime для перевірки URL приєднання

Параметр createTime слугує захистом від застарілих Join URL:

Зустріч створюється та повертає createTime: 1715261728123.

Join URL генерується з createTime=1715261728123.

Зустріч завершується та створюється знову з новим createTime.

Старий Join URL із попереднім createTime відхиляється.

Це запобігає входу користувачів із застарілими посиланнями-запрошеннями до нової зустрічі, яка повторно використовує той самий meetingID.

У bbbserver.de для учасників, які приєднуються через кімнати або посилання-запрошення у вебінтерфейсі bbbserver.de, URL-адреса приєднання генерується автоматично. Якщо ви використовуєте Integration API, сформуйте виклик join самостійно, як описано вище.

Поради з безпеки

Ніколи не розкривайте shared secret на стороні клієнта для обчислення URL приєднання. Завжди генеруйте URL приєднання на стороні сервера та передавайте їх клієнту.

  • Згенерований URL приєднання містить checksum і має використовуватися лише один раз.
  • Join URL слід генерувати на стороні сервера та передавати клієнту.
  • Для чутливих зустрічей використовуйте guest=true разом із guestPolicy=ASK_MODERATOR.

Перехід від password до role є однією з найважливіших несумісних змін у BBB 3.0. Обов’язково оновіть свою інтеграцію відповідним чином.

Поширені запитання

У BBB 3.0 і новіших версіях параметр role (MODERATOR або VIEWER) замінює призначення ролей на основі пароля, що використовувалося в попередніх версіях. Параметр password є застарілим і більше не повинен використовуватися в нових інтеграціях.

Замість перенаправлення браузера до зустрічі сервер повертає відповідь XML, що містить URL приєднання та токен сесії. Це корисно для серверних інтеграцій, яким потрібно перевіряти відповідь або програмно керувати токеном сесії.

Так. Використовуйте параметр existingUserID із внутрішнім ідентифікатором користувача з попередньої сесії для повторного підключення. Ви також можете передати replaceSessionToken, щоб замінити стару сесію. Зверніть увагу, що ці параметри не задокументовані й можуть змінитися без попередження.

Коли guest встановлено в true, користувач позначається як гість і підпадає під дію guestPolicy, визначеної під час створення зустрічі. Наприклад, із ASK_MODERATOR модератор повинен схвалити гостя, перш ніж той зможе увійти.

Параметри Userdata (userdata-=) дозволяють передавати користувацькі дані до клієнта зустрічі для кожного користувача окремо. Їх можна використовувати для налаштування поведінки клієнта, передавання інформації плагінам або персоналізації користувацького досвіду.

Ця помилка виникає, коли значення createTime у вашому URL приєднання не збігається зі значенням createTime поточної активної зустрічі. Зазвичай це трапляється, коли зустріч було завершено й створено знову з тим самим meetingID, але URL приєднання все ще містить старий createTime.
Посібник з API BigBlueButton