Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.
getJoinUrl – Згенерувати URL для приєднання
Кінцева точка getJoinUrl генерує нову URL-адресу приєднання для користувача, який уже приєднався до зустрічі. Це дозволяє тому самому користувачеві відкривати додаткові сесії — наприклад, на другому екрані або після зміни пристрою — без повторної автентифікації через стандартний потік join. BBB 3.0+
Ендпоінт
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters> Ця кінцева точка використовує автентифікацію session-token замість стандартного механізму контрольної суми shared-secret. Користувач уже має приєднатися через кінцеву точку join і мати дійсний sessionToken.
На відміну від кінцевих точок API BigBlueButton, захищених контрольною сумою, які повертають XML, ця кінцева точка повертає JSON.
Обов’язкові параметри
| Параметр | Тип | Обов’язково | За замовчуванням | Опис |
|---|---|---|---|---|
sessionToken | String | Так | — | sessionToken користувача, для якого слід згенерувати нову URL-адресу приєднання. |
Необов’язкові параметри
| Параметр | Тип | Обов’язково | За замовчуванням | Опис |
|---|---|---|---|---|
replaceSession | Boolean | Ні | false | Якщо встановлено значення true, оригінальна сесія анулюється та замінюється новою (перенесення сесії). |
sessionName | String | Ні | — | Описова назва для нової сесії. |
enforceLayout | String | Ні | — | Перевизначити макет для нової сесії. |
userdata-* | String | Ні | — | Користувацькі дані для нової сесії. Ключі мають починатися з префікса userdata-. |
Випадки використання
- Гібридні сценарії — модератор використовує один екран для презентації, а другий — для перегляду учасників.
- Перемикання пристроїв — користувач переходить зі свого комп’ютера на планшет під час зустрічі.
- Багатоекранні конфігурації — конференц-зала з кількома дисплеями, що показують різні макети.
Поведінка
Нова сесія використовує ту саму ідентичність користувача, що й оригінальна сесія. Користувач відображається у списку учасників лише один раз.
Без replaceSession обидві сесії існують паралельно.
З replaceSession=true оригінальна сесія анулюється, і користувача безшовно переводять до нової сесії.
Приклад запиту
GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS Приклад відповіді (успіх)
{
"response": {
"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
}
} Відповіді з помилками
Якщо запит завершується помилкою, кінцева точка повертає об’єкт JSON з описовим повідомленням про помилку:
{
"response": {
"returncode": "FAILED",
"message": "<error message>"
}
} | Повідомлення | Значення |
|---|---|
You must provide a session token | Відсутній параметр sessionToken. |
Invalid session token | sessionToken недійсний або строк його дії минув. |
Invalid Session | Запит не містить файлу cookie сеансу HTTP, створеного join, а конференція не дозволяє запитів без сеансу (allowRequestsWithoutSession, за замовчуванням false). |
Access denied | Користувача не знайдено або він не має дозволу. |
Meeting not found | Зустріч не існує або більше не виконується. |
У BigBlueButton 3.0 лише Meeting not found повертається як помилка JSON. Для інших перелічених вище помилок кінцева точка не надсилає відповіді JSON.
Список блокування Userdata
Під час використання параметрів userdata-* із getJoinUrl налаштовуваний список блокування (getJoinUrlUserdataBlocklist) обмежує певні ключі userdata для користувачів без прав модератора:
- Якщо список блокування містить значення
"all", для глядачів блокуються усі параметри userdata. - Модератори обходять список блокування, окрім випадків у breakout rooms.
- Параметр
enforceLayoutзавжди дозволений, незалежно від списку блокування.
Кінцева точка доступна лише тоді, коли користувач уже має дійсний sessionToken — тобто він спочатку має приєднатися до зустрічі через стандартну кінцеву точку join. Прострочені токени відхиляються.
Для сценаріїв перемикання пристроїв встановіть replaceSession=true, щоб безшовно перенести сесію на новий пристрій. Це дозволяє уникнути застарілої сесії на старому пристрої, яка може спричинити плутанину у списку учасників.