Глава 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 служит защитой от устаревших URL входа:

Встреча создаётся и возвращает createTime: 1715261728123.

URL входа генерируется с createTime=1715261728123.

Встреча завершается и создаётся заново с новым createTime.

Старый URL входа с предыдущим createTime отклоняется.

Это предотвращает вход пользователей с устаревшими ссылками-приглашениями в новую встречу, которая повторно использует тот же meetingID.

На bbbserver.de URL входа всегда генерируется на стороне сервера с правильными checksum и параметрами. Вам не нужно формировать URL входа вручную.

Советы по безопасности

Никогда не раскрывайте shared secret на стороне клиента для вычисления URL входа. Всегда генерируйте URL входа на стороне сервера и передавайте их клиенту.

  • Сгенерированный URL входа содержит checksum и должен использоваться только один раз.
  • 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