Версія API: 4.x найновіша 3.x

Ви переглядаєте документацію API для BigBlueButton 3.x. Поточна версія — BigBlueButton 4.x. Плануєте оновлення? У посібнику з міграції наведено всі зміни, які потрібно внести у ваші виклики API.

Розділ 10 GET POST

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 секунд) Лише користувачі, які наразі підключені
Варіант використання Огляд панелі керування та моніторингу Цільова перевірка конкретної зустрічі

Типові сценарії використання

  • Логіка входу — перевіряйте, чи присутній модератор, перш ніж перенаправляти гостей до зустрічі.
  • Списки учасників — відображайте поточних учасників у зовнішньому застосунку або на сторінці очікування.
  • Стан запису — перевірте, чи ввімкнено запис для конференції.
  • Налагодження — виконуйте детальний аналіз конкретної зустрічі для усунення проблем.
На bbbserver.de кінцева точка 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. Якщо користувацькі дані не було надано, елемент залишається порожнім.
Посібник з API BigBlueButton