API-Version: 4.x neueste 3.x
Kapitel 11 GET POST

getMeetingInfo – Meeting-Details abrufen

Der Endpunkt getMeetingInfo gibt detaillierte Informationen zu einem einzelnen BigBlueButton-Meeting zurück, einschließlich seiner aktuellen Teilnehmer, Metadaten, Konfigurationseinstellungen und des Aufzeichnungsstatus. Verwenden Sie ihn, um ein bestimmtes Meeting in Echtzeit zu prüfen.

Endpunkt

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?<parameter>&checksum=replace-with-checksum

Dieser Endpunkt erfordert eine gültige Prüfsumme, die aus dem Shared Secret Ihres BigBlueButton-Servers berechnet wird. Sowohl GET- als auch POST-Anfragen werden unterstützt.

Parameter

Parameter Typ Erforderlich Beschreibung
meetingID String Ja Die Meeting-Kennung des abzufragenden Meetings. Dies ist die ID, die Sie beim Erstellen des Meetings angegeben haben.

Antwortfelder

Eine erfolgreiche Antwort enthält die folgenden Felder, die das Meeting und seinen aktuellen Zustand beschreiben:

Feld Typ Beschreibung
returncode String Gibt an, ob der Aufruf erfolgreich war. Gibt SUCCESS oder FAILED zurück.
meetingName String Der menschenlesbare Name des Meetings.
meetingID String Die externe Meeting-Kennung, wie sie bei der Erstellung angegeben wurde.
internalMeetingID String Die interne eindeutige Kennung, die von BigBlueButton erzeugt wird.
createTime Long Zeitstempel (in Millisekunden seit der Unix-Epoche), wann das Meeting erstellt wurde.
createDate String Menschenlesbares Datum und Uhrzeit, wann das Meeting erstellt wurde.
voiceBridge String Die Voice-Bridge-Nummer für die telefonische Einwahl.
dialNumber String Die Telefonnummer für den Einwahlzugang, falls konfiguriert.
attendeePW String deprecated Das Teilnehmerpasswort. Aus Gründen der Abwärtskompatibilität enthalten, aber seit BigBlueButton 2.5 veraltet.
moderatorPW String deprecated Das Moderatorpasswort. Aus Gründen der Abwärtskompatibilität enthalten, aber seit BigBlueButton 2.5 veraltet.
running Boolean Ob das Meeting derzeit läuft (true) oder nicht (false).
duration Integer Die maximale Dauer des Meetings in Minuten. Ein Wert von 0 bedeutet unbegrenzt.
hasUserJoined Boolean Ob mindestens ein Benutzer dem Meeting beigetreten ist.
recording Boolean Ob die Aufzeichnung für dieses Meeting aktiviert ist.
hasBeenForciblyEnded Boolean Wird beim Beenden der Konferenz auf true gesetzt, unabhängig davon, wie sie beendet wurde. Da BigBlueButton eine beendete Konferenz sofort aus dem Speicher entfernt, enthalten Antworten praktisch immer false.
startTime Long Zeitstempel (in Millisekunden), wann das Meeting gestartet wurde.
endTime Long Zeitstempel (in Millisekunden), wann das Meeting beendet wurde. Gibt 0 zurück, wenn es noch läuft.
participantCount Integer Die Gesamtzahl der Teilnehmer, die sich derzeit im Meeting befinden.
listenerCount Integer Die Anzahl der Teilnehmer im Nur-Zuhören-Modus.
voiceParticipantCount Integer Die Anzahl der Teilnehmer, die dem Audiokanal beigetreten sind.
videoCount Integer Die Anzahl der Webcam-Streams, die derzeit im Meeting geteilt werden.
maxUsers Integer Die maximal zulässige Anzahl von Benutzern. Ein Wert von 0 bedeutet unbegrenzt.
moderatorCount Integer Die Anzahl der Moderatoren, die sich derzeit im Meeting befinden.
attendees XML Container Enthält eine Liste von attendee-Elementen mit Details zu jedem verbundenen Teilnehmer (siehe Teilnehmerfelder unten).
metadata XML Container Enthält die benutzerdefinierten Metadaten-Schlüssel-Wert-Paare, die bei der Erstellung des Meetings übergeben wurden.
isBreakout Boolean Ob das Meeting ein Breakout-Raum ist.
parentMeetingID String Die interne Konferenz-ID (internalMeetingID) der übergeordneten Konferenz. Nur bei Breakout-Räumen vorhanden.
sequence Integer Die Sequenznummer des Breakout-Raums. Nur bei Breakout-Räumen vorhanden.
freeJoin Boolean Ob Teilnehmer frei wählen können, welchem Breakout-Raum sie beitreten möchten. Nur bei Breakout-Räumen vorhanden.
breakoutRooms XML Container Listet die mit diesem Meeting verknüpften Breakout-Raum-IDs auf. Nur vorhanden, wenn Breakout-Räume erstellt wurden.

Teilnehmerfelder

Jedes attendee-Element innerhalb von attendees enthält die folgenden Felder:

Feld Typ Beschreibung
userID String Die externe Benutzer-ID, die als userID an join übergeben wurde. Wenn keine übergeben wurde, wird die von BigBlueButton generierte interne Benutzer-ID (Format w_xxxxxxxxxxxx) zurückgegeben.
fullName String Der Anzeigename des Teilnehmers.
role Enum Die Rolle des Teilnehmers: MODERATOR oder VIEWER. Per Telefon eingewählte Benutzer werden mit DIAL-IN-USER aufgeführt.
isPresenter Boolean Ob der Teilnehmer derzeit der Präsentierende ist.
isListeningOnly Boolean Ob sich der Teilnehmer im Nur-Zuhören-Modus befindet.
hasJoinedVoice Boolean Ob der Teilnehmer dem Audiokanal mit einem Mikrofon beigetreten ist.
hasVideo Boolean Ob der Teilnehmer seine Webcam teilt.
clientType String Der Typ des Clients, den der Teilnehmer verwendet. Typischerweise HTML5.
customdata XML Container Enthält die userdata-*-Parameter, die an join übergeben wurden, als untergeordnete XML-Elemente (ohne Präfix). Für jeden Teilnehmer vorhanden, der über join beigetreten ist; leer, wenn keine solchen Parameter übergeben wurden.

Beispielanfrage

GET https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?meetingID=replace-with-meeting-id&checksum=replace-with-checksum

Beispielantwort (Erfolg)

<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>

Fehlerantwort

Wenn die angegebene Meeting-ID nicht existiert oder bereits beendet wurde, gibt die API eine FAILED-Antwort zurück:

<response>
  <returncode>FAILED</returncode>
  <messageKey>notFound</messageKey>
  <message>A meeting with that ID does not exist</message>
</response>

Ein Fehler notFound bedeutet nicht unbedingt, dass das Meeting nie erstellt wurde. Es kann bereits beendet und aus dem Serverspeicher entfernt worden sein. BigBlueButton hält Meeting-Daten nur vor, solange das Meeting aktiv ist.

getMeetingInfo vs. getMeetings

Aspekt getMeetings getMeetingInfo
Umfang Alle aktiven Meetings auf dem Server Ein einzelnes bestimmtes Meeting
Parameter Keine erforderlich meetingID erforderlich
Teilnehmerdetails Verbundene Benutzer sowie Benutzer, die das Meeting kürzlich verlassen haben (werden standardmäßig nach 60 Sekunden entfernt) Nur aktuell verbundene Benutzer
Anwendungsfall Dashboard- und Monitoring-Übersicht Gezielte Prüfung eines bestimmten Meetings

Häufige Anwendungsfälle

  • Join-Logik — prüfen, ob ein Moderator anwesend ist, bevor Gäste in das Meeting weitergeleitet werden.
  • Teilnehmerlisten — aktuelle Teilnehmer in einer externen Anwendung oder Lobby-Seite anzeigen.
  • Aufzeichnungsstatus — prüfen Sie, ob die Aufzeichnung für das Meeting aktiviert ist.
  • Debugging — eine detaillierte Analyse eines bestimmten Meetings zur Fehlerbehebung durchführen.
Auf bbbserver.de ist der Endpunkt getMeetingInfo in allen Tarifen verfügbar. Ihre API-Zugangsdaten finden Sie im Server-Management-Dashboard.

Tipps

Pollen Sie getMeetingInfo regelmäßig, um eine Live-Teilnehmerliste aufzubauen. Kombinieren Sie die Felder voiceParticipantCount und videoCount, um festzustellen, wie viele Benutzer aktiv mit Audio und Video beteiligt sind.

Verwenden Sie den Container metadata, um anwendungsspezifische Daten wie Ursprungssystem, Callback-URLs oder benutzerdefinierte Labels zu übergeben und abzurufen, ohne in die internen Abläufe von BigBlueButton einzugreifen.

Die Felder attendeePW und moderatorPW sind seit BigBlueButton 2.5 veraltet. Sie werden aus Gründen der Abwärtskompatibilität weiterhin zurückgegeben, aber Sie sollten sich in neuen Integrationen für die Authentifizierungslogik nicht auf sie verlassen.

Häufig gestellte Fragen

Sie erhalten eine FAILED-Antwort mit dem messageKey "notFound". BigBlueButton entfernt Meeting-Daten aus dem Speicher, sobald ein Meeting beendet wurde. Um auf Informationen über vergangene Meetings zuzugreifen, verwenden Sie stattdessen den Endpunkt getRecordings.

Nein. Die Teilnehmerliste enthält nur Teilnehmer, die aktuell mit dem Meeting verbunden sind. Benutzer, die das Meeting verlassen haben, sind nicht mehr enthalten. Im Gegensatz dazu führt getMeetings weiterhin Benutzer auf, die das Meeting kürzlich verlassen haben, bis BigBlueButton sie entfernt (standardmäßig nach 60 Sekunden).

Es gibt kein festes Rate Limit, das von BigBlueButton selbst erzwungen wird, aber häufiges Polling (z. B. jede Sekunde) kann den Server unnötig belasten. Ein Polling-Intervall von 5 bis 10 Sekunden ist für die meisten Anwendungsfälle typischerweise ausreichend.

Ja. Rufen Sie getMeetingInfo mit der meetingID auf. Wenn der returncode der Antwort SUCCESS ist, existiert das Meeting und ist aktiv. Wenn er FAILED mit messageKey "notFound" ist, existiert das Meeting nicht oder wurde bereits beendet.

Felder wie parentMeetingID, sequence, freeJoin und breakoutRooms erscheinen nur dann in der Antwort, wenn das Meeting ein Gruppenraum ist oder Gruppenräume hat. Bei normalen Meetings ist isBreakout false und die anderen Gruppenraum-Felder werden weggelassen.

Der customdata-Container enthält benutzerspezifische Schlüssel-Wert-Paare, die als userdata-*-Parameter übergeben wurden, als der Benutzer dem Meeting über den API-Aufruf join beigetreten ist. Jeder Schlüssel (ohne das Präfix userdata-) wird zu einem untergeordneten XML-Element. Wenn keine benutzerdefinierten Daten übergeben wurden, ist das Element leer.