Przegląd API
API BigBlueButton to interfejs oparty na HTTP, który umożliwia zewnętrznym aplikacjom — takim jak systemy zarządzania nauczaniem, portale internetowe i niestandardowe integracje — programowe tworzenie, kontrolowanie i monitorowanie spotkań. Wszystkie wywołania API są zabezpieczone za pomocą mechanizmu checksum opartego na shared secret.
Jak działa API
API BBB stosuje prosty model żądanie-odpowiedź. Wysyłasz żądanie HTTPS do określonego punktu końcowego na swoim serwerze BigBlueButton, a serwer odpowiada dokumentem XML wskazującym powodzenie lub niepowodzenie.
- Protokół: HTTPS (GET lub POST)
- Bazowy URL:
https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash> - Format odpowiedzi: XML (z kilkoma wyjątkami, które zwracają JSON)
- Uwierzytelnianie: Shared-secret-oparta checksum (bez OAuth, bez klucza API)
Kategorie endpointów
Endpointy API są zorganizowane w następujące kategorie:
| Kategoria | Endpointy | Opis |
|---|---|---|
| Administracja | create, join, end | Tworzenie, dołączanie do i kończenie spotkań |
| Monitorowanie | isMeetingRunning, getMeetings, getMeetingInfo | Monitorowanie uruchomionych spotkań |
| Nagrania | getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack | Zarządzanie nagraniami spotkań |
| Webhooks | hooks/create, hooks/list, hooks/destroy | Powiadomienia o zdarzeniach w czasie rzeczywistym |
| Wiadomości | sendChatMessage | Wysyłanie wiadomości czatu BBB 3.0+ |
| Sesja | getJoinUrl, feedback | Zarządzanie sesją BBB 3.0+ |
Metody HTTP
Większość punktów końcowych akceptuje zarówno żądania GET, jak i POST. Przy użyciu POST pamiętaj, że checksum jest obliczana na podstawie URL query string, a nie z treści żądania. Treść POST może zawierać dodatkowe dane, takie jak prezentacja XML lub nadpisania ustawień klienta.
Nawet podczas wysyłania żądania POST, checksum musi być obliczona na podstawie parametrów query string w URL. Zawartość treści nie jest uwzględniana w obliczeniu checksum.
Format odpowiedzi
Każda odpowiedź API zawiera co najmniej następujące pola:
<response>
<returncode>SUCCESS</returncode>
<!-- or -->
<returncode>FAILED</returncode>
<messageKey>errorKey</messageKey>
<message>Human-readable error message</message>
</response>| Pole | Opis |
|---|---|
returncode | Zawsze SUCCESS lub FAILED |
messageKey | Kod błędu czytelny dla maszyny (występuje tylko w przypadku błędów lub ostrzeżeń) |
message | Opis błędu lub ostrzeżenia czytelny dla człowieka |
Wersjonowanie API
API BigBlueButton nie używa tradycyjnego wersjonowania opartego na URL-ach (brak ścieżek /v1/, /v2/). Zamiast tego nowe parametry są dodawane w sposób zgodny wstecznie, a przestarzałe parametry są odpowiednio oznaczane, ale nie są natychmiast usuwane.
| Wersja BBB | Istotne zmiany w API |
|---|---|
| 2.2 | ustawienia Lock, allowModsToUnmuteUsers |
| 2.4 | logo, meetingLayout, allowModsToEjectCameras, Panel nauki |
| 2.5 | disabledFeatures, obsługa SHA-384/SHA-512, webhook eventID filtr |
| 2.6 | notifyRecordingIsOn, presentationUploadExternalUrl, tryb ciemny |
| 2.7 | preUploadedPresentation (pojedynczy URL), nagrywanie pagination |
| 3.0 | sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role zastępuje password w join |
Nieudokumentowane endpointy
Następujące punkty końcowe istnieją w kodzie źródłowym BigBlueButton, ale nie są opisane w oficjalnej dokumentacji. Są używane wewnętrznie i mogą ulec zmianie bez powiadomienia.
| Punkt końcowy | Metoda | Opis | Status |
|---|---|---|---|
/api/stuns | GET POST | Zwraca konfigurację serwera STUN/TURN dla połączeń WebRTC | Undocumented |
/api/signOut | GET POST | Zakończ sesję / wyloguj użytkownika | Undocumented |
/api/guestWait | GET | Sprawdź status lobby dla gości oczekujących na zatwierdzenie przez moderatora | Undocumented |
/api/getSessions | GET POST | Pobierz informacje o sesji | Undocumented |
/api/learningDashboard | GET POST | Pobierz dane analityki uczenia | Undocumented |
Mutacje GraphQL (akcje w trakcie spotkania)
Od BBB 3.0 większość działań w czasie rzeczywistym w trakcie spotkania jest obsługiwana przez mutacje GraphQL przez WebSocket. Są one używane wewnętrznie przez klienta BBB HTML5 i nie są częścią klasycznego API REST.
| Kategoria | Liczba | Przykłady |
|---|---|---|
| Czat | 9 | chatSendMessage, chatDeleteMessage, chatEditMessage |
| Zarządzanie użytkownikami | 26 | userSetMuted, userSetRole, userEjectFromMeeting |
| Prezentacja | 11 | presentationSetCurrent, presentationSetPage |
| Kontrola spotkania | 8 | meetingEnd, meetingRecordingSetStatus |
| Pokoje podgrup | 7 | breakoutRoomCreate, breakoutRoomEndAll |
| Ankiety | 4 | pollCreate, pollSubmitUserVote, pollPublishResult |
| Minutnik | 8 | timerStart, timerStop, timerReset |
| Wtyczki | 8 | pluginDataChannelPushEntry, pluginPersistEvent |
Warstwa GraphQL jest przeznaczona do wewnętrznego użytku klienta i nie zapewnia stabilnego publicznego API. Mutacje i ich parametry mogą się zmieniać między wersjami BBB bez powiadomienia.
Wymagania wstępne
Zanim zaczniesz korzystać z API BigBlueButton, upewnij się, że masz przygotowane następujące elementy:
Działający serwer BigBlueButton (zalecana wersja 3.0)
Wspólny sekret (nazywany również „security salt”), skonfigurowany w /etc/bigbluebutton/bbb-web.properties
Dostęp HTTPS do serwera
Aplikację po stronie serwera, która generuje wywołania API — shared secret nigdy nie może być ujawniony po stronie klienta
Nigdy nie ujawniaj shared secret w kodzie po stronie klienta (JavaScript, aplikacje mobilne). Wszystkie wywołania API muszą być generowane po stronie serwera, aby zapobiec nieautoryzowanemu dostępowi do twojego serwera BigBlueButton.
bbbserver.de — IntegrationAPI
bbbserver.de to platforma premium hostingu BigBlueButton z siedzibą w UE, z serwerami zlokalizowanymi w UE. IntegrationAPI to proxy, które w pełni replikuje standardowe API BBB — zewnętrzne aplikacje łączą się przez standardowe wtyczki BBB i zachowują się tak, jakby komunikowały się z pojedynczym serwerem BBB. W tle bbbserver automatycznie rozdziela konferencje między wiele serwerów z wystarczającą pojemnością.
Twój URL API i shared secret są dostępne w panelu administracyjnym bbbserver w sekcji Customer Settings → IntegrationAPI. IntegrationAPI można tam włączyć lub wyłączyć.
Kompatybilność Plugin
Następujące platformy działają od razu — wystarczy podać URL API i shared secret:
- Moodle (BigBlueButtonBN)
- ILIAS
- Nextcloud
- WordPress
- Greenlight
Różnice względem standardowego API
| Temat | Szczegół |
|---|---|
maxParticipants / duration | Używane do rezerwacji pojemności, a nie tylko jako limity. Wartości domyślne, jeśli nie podano: 5 uczestników, 60 minut. |
duration zachowanie | NIE kończy automatycznie spotkań — służy wyłącznie do planowania pojemności. |
| Dodatkowy parametr | deactivateBbbserverDefaultChatTexts — do celów white-labeling. |
| Niedostępne endpointy | updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks |
| Webhooks | Tylko dla konkretnego spotkania, z maskowaniem prywatności. |
| Limity szybkości | Brak limitów szybkości dla IntegrationAPI. |
Oprócz IntegrationAPI, bbbserver.de oferuje osobne System API z funkcjami specyficznymi dla platformy, takimi jak zarządzanie kontem i statystyki użycia. System API nie jest kompatybilne z BBB i nie jest omówione w tym przewodniku.