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

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

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

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

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

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

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

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

Никогда не раскрывайте 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