Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.
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.
join самостоятельно, как описано выше.Советы по безопасности
Никогда не раскрывайте shared secret на стороне клиента для вычисления URL входа. Всегда генерируйте URL входа на стороне сервера и передавайте их клиенту.
- Сгенерированный URL входа содержит checksum и должен использоваться только один раз.
- URL входа следует генерировать на стороне сервера и передавать клиенту.
- Для конфиденциальных встреч используйте
guest=trueвместе сguestPolicy=ASK_MODERATOR.
Переход от password к role — одно из самых значительных несовместимых изменений в BBB 3.0. Обязательно обновите вашу интеграцию соответствующим образом.
Часто задаваемые вопросы
role (MODERATOR или VIEWER) заменяет назначение ролей по паролю, использовавшееся в более ранних версиях. Параметр password устарел и больше не должен использоваться в новых интеграциях.existingUserID с внутренним идентификатором пользователя из предыдущей сессии для повторного подключения. Вы также можете передать replaceSessionToken, чтобы заменить старую сессию. Обратите внимание, что эти параметры не документированы и могут измениться без предупреждения.guest установлено в true, пользователь помечается как гость и подпадает под действие guestPolicy, заданной при создании встречи. Например, при ASK_MODERATOR модератор должен одобрить гостя, прежде чем тот сможет войти.userdata-= ) позволяют передавать пользовательские данные в клиент встречи для каждого пользователя отдельно. Их можно использовать для настройки поведения клиента, передачи информации плагинам или персонализации пользовательского опыта.createTime в вашем URL входа не совпадает со значением createTime текущей запущенной встречи. Обычно это происходит, когда встреча была завершена и создана заново с тем же meetingID, но URL входа всё ещё содержит старое значение createTime.