Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.
getMeetingInfo – Отримати деталі зустрічі
Кінцева точка getMeetingInfo повертає докладну інформацію про одну зустріч BigBlueButton, включно з поточними учасниками, метаданими, налаштуваннями конфігурації та статусом запису. Використовуйте її для перевірки конкретної зустрічі в реальному часі.
Ендпоінт
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?<parameter>&checksum=replace-with-checksum Ця кінцева точка вимагає дійсної контрольної суми, обчисленої зі спільного секрету вашого сервера BigBlueButton. Підтримуються як запити GET, так і POST.
Параметри
| Параметр | Тип | Обов’язково | Опис |
|---|---|---|---|
meetingID | String | Так | Ідентифікатор зустрічі, для якої виконується запит. Це ID, який ви вказали під час створення зустрічі. |
Поля відповіді
Успішна відповідь містить такі поля, що описують зустріч та її поточний стан:
| Поле | Тип | Опис |
|---|---|---|
returncode | String | Вказує, чи був виклик успішним. Повертає SUCCESS або FAILED. |
meetingName | String | Зрозуміла для людини назва зустрічі. |
meetingID | String | Зовнішній ідентифікатор зустрічі, вказаний під час створення. |
internalMeetingID | String | Внутрішній унікальний ідентифікатор, згенерований BigBlueButton. |
createTime | Long | Позначка часу (у мілісекундах від епохи), коли зустріч була створена. |
createDate | String | Зрозумілі для людини дата й час, коли зустріч була створена. |
voiceBridge | String | Номер голосового мосту для телефонного підключення. |
dialNumber | String | Телефонний номер для доступу через дзвінок, якщо налаштовано. |
attendeePW | String deprecated | Пароль учасника. Включений для зворотної сумісності, але застарілий, починаючи з BigBlueButton 2.5. |
moderatorPW | String deprecated | Пароль модератора. Включений для зворотної сумісності, але застарілий, починаючи з BigBlueButton 2.5. |
running | Boolean | Чи активна зустріч зараз (true) чи ні (false). |
duration | Integer | Максимальна тривалість зустрічі в хвилинах. Значення 0 означає без обмежень. |
hasUserJoined | Boolean | Чи приєднався до зустрічі принаймні один користувач. |
recording | Boolean | Чи ввімкнено запис для цієї зустрічі. |
hasBeenForciblyEnded | Boolean | Набуває значення true після завершення зустрічі, незалежно від способу її завершення. Оскільки BigBlueButton одразу видаляє завершену зустріч із пам’яті, відповіді практично завжди містять false. |
startTime | Long | Позначка часу (у мілісекундах), коли зустріч почалася. |
endTime | Long | Позначка часу (у мілісекундах), коли зустріч завершилася. Повертає 0, якщо вона все ще триває. |
participantCount | Integer | Загальна кількість учасників, які зараз перебувають на зустрічі. |
listenerCount | Integer | Кількість учасників у режимі лише прослуховування. |
voiceParticipantCount | Integer | Кількість учасників, які приєдналися до аудіоканалу. |
videoCount | Integer | Кількість потоків із вебкамер, які зараз транслюються в конференції. |
maxUsers | Integer | Максимальна дозволена кількість користувачів. Значення 0 означає без обмежень. |
moderatorCount | Integer | Кількість модераторів, які зараз перебувають на зустрічі. |
attendees | XML Container | Містить список елементів attendee з деталями про кожного підключеного учасника (див. поля Attendee нижче). |
metadata | XML Container | Містить користувацькі пари ключ-значення метаданих, передані під час створення зустрічі. |
isBreakout | Boolean | Чи є зустріч сесійною кімнатою. |
parentMeetingID | String | Внутрішній ідентифікатор зустрічі (internalMeetingID) для батьківської зустрічі. Наявний лише для кімнат для групової роботи. |
sequence | Integer | Порядковий номер сесійної кімнати. Присутній лише для сесійних кімнат. |
freeJoin | Boolean | Чи можуть учасники вільно обирати, до якої сесійної кімнати приєднатися. Присутній лише для сесійних кімнат. |
breakoutRooms | XML Container | Перелічує ідентифікатори кімнат для групової роботи, пов’язаних із цією зустріччю. Присутнє лише тоді, коли кімнати для групової роботи були створені. |
Поля учасника
Кожен елемент attendee у межах attendees містить такі поля:
| Поле | Тип | Опис |
|---|---|---|
userID | String | Зовнішній ідентифікатор користувача, переданий як userID до join. Якщо його не передано, повертається внутрішній ідентифікатор користувача, згенерований BigBlueButton (формат w_xxxxxxxxxxxx). |
fullName | String | Відображуване ім’я учасника. |
role | Enum | Роль учасника: MODERATOR або VIEWER. Користувачі, які приєдналися телефоном, зазначаються з роллю DIAL-IN-USER. |
isPresenter | Boolean | Чи є учасник наразі презентером. |
isListeningOnly | Boolean | Чи перебуває учасник у режимі лише прослуховування. |
hasJoinedVoice | Boolean | Чи приєднався учасник до аудіоканалу з мікрофоном. |
hasVideo | Boolean | Чи транслює учасник свою вебкамеру. |
clientType | String | Тип клієнта, який використовує учасник. Зазвичай HTML5. |
customdata | XML Container | Містить параметри userdata-*, передані до join, як дочірні елементи XML (без префікса). Наявний для кожного учасника, який приєднався через join; порожній, якщо таких параметрів не було передано. |
Приклад запиту
GET https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?meetingID=replace-with-meeting-id&checksum=replace-with-checksum Приклад відповіді (успіх)
<response>
<returncode>SUCCESS</returncode>
<meetingName>Project Discussion</meetingName>
<meetingID>replace-with-meeting-id</meetingID>
<internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
<createTime>1715261728123</createTime>
<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
<voiceBridge>66052</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<attendeePW>replace-with-password</attendeePW>
<moderatorPW>replace-with-password</moderatorPW>
<running>true</running>
<duration>0</duration>
<hasUserJoined>true</hasUserJoined>
<recording>true</recording>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<startTime>1715261728142</startTime>
<endTime>0</endTime>
<participantCount>3</participantCount>
<listenerCount>1</listenerCount>
<voiceParticipantCount>2</voiceParticipantCount>
<videoCount>2</videoCount>
<maxUsers>0</maxUsers>
<moderatorCount>1</moderatorCount>
<attendees>
<attendee>
<userID>replace-with-user-id</userID>
<fullName>Max Mustermann</fullName>
<role>MODERATOR</role>
<isPresenter>true</isPresenter>
<isListeningOnly>false</isListeningOnly>
<hasJoinedVoice>true</hasJoinedVoice>
<hasVideo>true</hasVideo>
<clientType>HTML5</clientType>
<customdata></customdata>
</attendee>
</attendees>
<metadata>
<bbb-origin>greenlight</bbb-origin>
<bbb-origin-version>v3.1.0</bbb-origin-version>
<endcallbackurl>https://api-guide.bbbserver.com/callbacks/meeting-ended</endcallbackurl>
</metadata>
<isBreakout>false</isBreakout>
</response> Відповідь з помилкою
Якщо вказаний ідентифікатор зустрічі не існує або зустріч уже завершена, API повертає відповідь FAILED:
<response>
<returncode>FAILED</returncode>
<messageKey>notFound</messageKey>
<message>A meeting with that ID does not exist</message>
</response> Помилка notFound не обов’язково означає, що зустріч ніколи не була створена. Вона вже могла завершитися й бути видаленою з пам’яті сервера. BigBlueButton зберігає дані зустрічі лише поки зустріч активна.
getMeetingInfo проти getMeetings
| Аспект | getMeetings | getMeetingInfo |
|---|---|---|
| Обсяг | Усі активні зустрічі на сервері | Одна конкретна зустріч |
| Параметри | Не потрібно | meetingID обов’язково |
| Деталі учасника | Підключені користувачі та користувачі, які нещодавно вийшли (за замовчуванням видаляються через 60 секунд) | Лише користувачі, які наразі підключені |
| Варіант використання | Огляд панелі керування та моніторингу | Цільова перевірка конкретної зустрічі |
Типові сценарії використання
- Логіка входу — перевіряйте, чи присутній модератор, перш ніж перенаправляти гостей до зустрічі.
- Списки учасників — відображайте поточних учасників у зовнішньому застосунку або на сторінці очікування.
- Стан запису — перевірте, чи ввімкнено запис для конференції.
- Налагодження — виконуйте детальний аналіз конкретної зустрічі для усунення проблем.
getMeetingInfo доступна на всіх тарифах. Ви можете знайти свої облікові дані API в панелі керування сервером.Поради
Опитуйте getMeetingInfo періодично, щоб побудувати живий список учасників. Поєднуйте поля voiceParticipantCount і videoCount, щоб визначити, скільки користувачів активно залучені до аудіо й відео.
Використовуйте контейнер metadata для передавання й отримання специфічних для застосунку даних, таких як вихідна система, URL зворотного виклику або користувацькі мітки, не втручаючись у внутрішні механізми BigBlueButton.
Поля attendeePW і moderatorPW є застарілими, починаючи з BigBlueButton 2.5. Вони все ще повертаються для зворотної сумісності, але вам не слід покладатися на них у логіці автентифікації нових інтеграцій.
Поширені запитання
FAILED із messageKey "notFound". BigBlueButton видаляє дані зустрічі з пам’яті після її завершення. Щоб отримати інформацію про минулі зустрічі, використовуйте натомість кінцеву точку getRecordings.getMeetings і далі містить користувачів, які нещодавно вийшли, доки BigBlueButton не видалить їх (за замовчуванням через 60 секунд).BigBlueButton не накладає жорсткого обмеження частоти запитів, але часте опитування (наприклад, щосекунди) може створювати зайве навантаження на сервер. Для більшості сценаріїв зазвичай достатньо інтервалу опитування 5–10 секунд.getMeetingInfo з meetingID. Якщо поле returncode у відповіді дорівнює SUCCESS, зустріч існує й активна. Якщо це FAILED з messageKey "notFound", зустріч не існує або вже завершилася.parentMeetingID, sequence, freeJoin і breakoutRooms з’являються у відповіді лише тоді, коли зустріч є кімнатою для групової роботи або має такі кімнати. Для звичайних зустрічей isBreakout дорівнює false, а інші поля breakout опускаються.customdata містить специфічні для користувача пари «ключ — значення», передані як параметри userdata-*, коли користувач приєднався до конференції через виклик API join. Кожен ключ (без префікса userdata-) стає дочірнім елементом XML. Якщо користувацькі дані не було надано, елемент залишається порожнім.