Розділ 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 3.0+

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

Параметр Тип Опис
password String Застаріло Застаріло з BBB 3.0. Призначення ролей через пароль (attendeePW/moderatorPW з create). Замінено на role.

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

Параметр Тип За замовчуванням Опис
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.
‎⚠ Не задокументовано В офіційній документації це значення помилково вказано як PARTICIPANTS_CHAT_ONLY (без _AND_).
auth Boolean (умовно) ‎⚠ Не задокументовано Позначити користувача як автентифікованого. Умовна логіка: якщо guest не вказано, auth за замовчуванням має значення true. Якщо вказано guest=true, auth за замовчуванням має значення false, якщо не встановлено явно.
defaultLayout String — ‎⚠ Не задокументовано Типовий макет для цього користувача. Ті самі значення, що й для meetingLayout у виклику create.
sessionName String — ‎⚠ Не задокументовано Власна назва сесії. Працює лише в поєднанні з existingUserID.
existingUserID String — ‎⚠ Не задокументовано Внутрішній ідентифікатор користувача для повторного входу або перепідключення до наявної сесії.
replaceSessionToken String — ‎⚠ Не задокументовано Токен сесії, яку потрібно замінити (коли використовується разом із existingUserID).

Параметри Userdata

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

Певні ключі userdata можуть бути заблоковані на стороні сервера через список блокування (getJoinUrlUserdataBlocklist).

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

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>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?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 URL приєднання завжди генерується на стороні сервера з правильним checksum і параметрами. Вам не потрібно формувати URL приєднання вручну.

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

Ніколи не розкривайте 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