API-versie: 4.x nieuwste 3.x

Je bekijkt de API-documentatie voor BigBlueButton 3.x. De huidige versie is BigBlueButton 4.x. Plan je een upgrade? De migratiehandleiding vermeldt alle wijzigingen die je in je API-aanroepen moet aanbrengen.

Hoofdstuk 3 GET POST

create – Vergadering maken

Het endpoint create voorziet een nieuwe vergadering op de BigBlueButton-server. Als er al een vergadering met dezelfde meetingID bestaat, retourneert de server de bestaande vergadergegevens in plaats van een duplicaat aan te maken (idempotent gedrag).

Endpoint

POST GET

https://api-guide.bbbserver.com/bigbluebutton/api/create?<parameters>&checksum=replace-with-checksum

Vereiste parameters

Parameter Type Beschrijving
meetingID String Unieke vergaderingsidentifier (2 tot 256 tekens, geen komma's).
name String Weergavenaam van de vergadering (2 tot 256 tekens). Verplicht sinds BBB 2.4.

Optionele parameters

Algemeen

Parameter Type Standaard Beschrijving
attendeePW Deprecated String (auto) Wachtwoord voor toegang van deelnemers. Verouderd sinds BBB 3.0 — wordt automatisch gegenereerd.
moderatorPW Deprecated String (auto) Wachtwoord voor toegang van moderators. Verouderd sinds BBB 3.0 — wordt automatisch gegenereerd.
welcome String — Welkomstbericht dat wordt weergegeven in het dialoogvenster met sessiedetails. Ondersteunt tijdelijke aanduidingen: %%CONFNAME%%, %%DIALNUM%%, %%CONFNUM%%, %%SERVERURL%%.
moderatorOnlyMessage String — Bericht dat alleen aan moderators wordt getoond in het dialoogvenster met sessiedetails.
dialNumber String — Inbelnummer voor deelname via de telefoon.
voiceBridge String (auto) Vijf willekeurige cijfers (mogen met 0 beginnen, bijv. 07382), automatisch gegenereerd. Moet uniek zijn per vergadering.
maxParticipants Number 0 (unlimited) Maximum aantal deelnemers. Op bbbserver.de wordt deze waarde gebruikt voor capaciteitsreservering (zie de opmerkingen over bbbserver.de hieronder).
duration Number 0 (unlimited) Maximale duur in minuten. In standaard BBB eindigt de vergadering automatisch wanneer de tijd om is. Op bbbserver.de wordt dit alleen gebruikt voor capaciteitsplanning (zie de opmerkingen over bbbserver.de hieronder).
logoutURL String — URL waarnaar de gebruiker wordt doorgestuurd na het uitloggen.
loginURL String — URL die tijdens de vergadering toegankelijk wordt gemaakt voor gebruikers. BBB 3.0+
record Boolean false Schakel opname van media en gebeurtenissen in.
autoStartRecording Boolean false De opname start automatisch wanneer de eerste persoon deelneemt.
allowStartStopRecording Boolean true Sta gebruikers toe om de opname handmatig te starten en te stoppen.
recordFullDurationMedia Boolean false Neem media op gedurende de volledige duur van de vergadering. BBB 2.6.9+
muteOnStart Boolean true Demp alle deelnemers wanneer ze deelnemen.
guestPolicy Enum ALWAYS_ACCEPT Gastbeleid: ALWAYS_ACCEPT, ALWAYS_DENY of ASK_MODERATOR.
webVoice Deprecated Removed in 4.0 String (= voiceBridge) Verouderd. Selecteerde een afzonderlijke spraakconferentie voor de oude Flash-client en heeft sinds BBB 2.3 geen effect; de waarde valt altijd terug op voiceBridge.
meetingEndedURL String — Server-naar-server-callback-URL die wordt aangeroepen wanneer de vergadering eindigt. Anders dan bij meta_endCallbackUrl blijft deze aan de serverzijde en wordt deze niet doorgegeven aan de client of de metadata van de opname. De URL wordt ongewijzigd aangeroepen. BBB 2.2+
logoutTimer Undocumented Removed in 4.0 Number 0 (disabled) Bedoeld als time-out in minuten vóór automatisch uitloggen. De waarde wordt door bbb-web opgeslagen, maar bereikt de client nooit en heeft daarom geen effect.

Lay-out en uiterlijk

Parameter Type Standaard Beschrijving
meetingLayout Enum CUSTOM_LAYOUT Standaardlay-out. Mogelijke waarden: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
bannerText String — Bannertekst die in de client wordt getoond. BBB 2.0+
bannerColor String — Achtergrondkleur van de banner als hexadecimale waarde, bijvoorbeeld #FF0000. BBB 2.0+

Machtigingen en vergrendelingsinstellingen

Parameter Type Standaard Beschrijving
webcamsOnlyForModerator Boolean false Webcams alleen zichtbaar voor moderators.
allowModsToUnmuteUsers Boolean false Moderators toestaan om het dempen van andere gebruikers op te heffen. BBB 2.2+
allowModsToEjectCameras Boolean false Moderators toestaan om de camera's van andere gebruikers te sluiten. BBB 2.4+
allowPromoteGuestToModerator Boolean false Toestaan om gasten te promoveren naar de moderatorrol. BBB 2.7.9+
lockSettingsDisableCam Boolean false Cameradeling vergrendelen voor deelnemers. BBB 2.2+
lockSettingsDisableMic Boolean false Microfoon vergrendelen voor deelnemers (alleen luisteren). BBB 2.2+
lockSettingsDisablePrivateChat Boolean false Privéchats vergrendelen voor deelnemers. BBB 2.2+
lockSettingsDisablePublicChat Boolean false Openbare chat vergrendelen voor deelnemers. BBB 2.2+
lockSettingsDisableNotes Boolean false Gedeelde notities vergrendelen voor deelnemers. BBB 2.5+
De enkelvoudige alias lockSettingsDisableNote wordt nog steeds geaccepteerd, maar is verouderd (verwijderd in BBB 4.0).
lockSettingsHideUserList Boolean false Deelnemerslijst verbergen voor kijkers. BBB 2.2+
lockSettingsHideViewersCursor Boolean false Cursors van andere kijkers op het whiteboard verbergen. BBB 2.5+
lockSettingsHideViewersAnnotation Boolean false Whiteboardaantekeningen van andere kijkers verbergen. BBB 2.7+
lockSettingsLockOnJoin Boolean true Vergrendelingsinstellingen direct toepassen wanneer een gebruiker deelneemt. BBB 2.2+
lockSettingsLockOnJoinConfigurable Boolean false De instelling lockSettingsLockOnJoin inschakelen om te worden toegepast. BBB 2.2+

Webcam

Parameter Type Standaard Beschrijving
userCameraCap Number 3 Maximumaantal gelijktijdige webcams per gebruiker. BBB 2.4.5+
meetingCameraCap Number 0 (unlimited) Maximumaantal gelijktijdige webcams in de vergadering. BBB 2.5+
maxPinnedCameras Number 3 Maximumaantal vastgezette webcams. BBB 2.6+

Functies uitschakelen

Parameter Type Standaard Beschrijving
disabledFeatures String — Door komma's gescheiden lijst met uit te schakelen functies. BBB 2.5+
disabledFeaturesExclude String — Door komma's gescheiden lijst met functies die voor deze vergadering opnieuw moeten worden ingeschakeld (overschrijft server-side standaardinstellingen). BBB 2.6.9+

Beschikbare waarden voor disabledFeatures:

Waarde Beschrijving
breakoutRoomsBreakout-ruimtes
captions DeprecatedGetypte ondertiteling. Heeft sinds BBB 3.0 geen effect (getypte ondertiteling is verplaatst naar een plug-in); gebruik liveTranscription om automatische transcriptie uit te schakelen.
chatOpenbare en privéchat
privateChatAlleen privéchat
deleteChatMessageChatberichten verwijderen BBB 3.0+
editChatMessageChatberichten bewerken BBB 3.0+
replyChatMessageAntwoorden op chatberichten BBB 3.0+
chatMessageReactionsReacties op chatberichten BBB 3.0+
chatEmojiPickerEmoji-kiezer in chat BBB 3.0.9+
downloadPresentationWithAnnotationsGeannoteerde presentatie downloaden
downloadPresentationConvertedToPdfGeconverteerde presentatie downloaden
downloadPresentationOriginalFileOrigineel presentatiebestand downloaden
snapshotOfCurrentSlideMomentopname van de huidige dia
externalVideosExterne video delen
importPresentationWithAnnotationsFromBreakoutRoomsPresentatie importeren uit breakout-rooms
importSharedNotesFromBreakoutRoomsGedeelde notities importeren uit breakout-rooms
layouts Removed in 4.0Lay-outselectie (alleen standaardlay-out)
learningDashboardDashboard voor leeranalyses
learningDashboardDownloadSessionDataDashboardsessiegegevens downloaden
pollsPeilingen
screenshareScherm delen
sharedNotesGedeelde notities
virtualBackgroundsVirtuele achtergronden
customVirtualBackgroundsAangepaste virtuele achtergronden uploaden
liveTranscriptionLive-transcriptie
presentationPresentatie
cameraAsContentCamera als inhoud
timerTimer
infiniteWhiteboardOneindig whiteboard BBB 3.0+
raiseHandHand opsteken BBB 3.0.7+
userReactionsGebruikersreacties BBB 3.0.8+
reactionsEmoji-statusreacties (anders dan userReactions) BBB 2.7+
quizzesQuizzen BBB 3.0.11+
pluginsPlug-ins BBB 3.0.25+

Vergaderingslevenscyclus

Parameter Type Standaard Beschrijving
endWhenNoModerator Boolean false Beëindig de vergadering automatisch wanneer er geen moderator aanwezig is. BBB 2.3+
endWhenNoModeratorDelayInMinutes Number 1 Vertraging in minuten vóór automatische beëindiging wanneer er geen moderator aanwezig is. BBB 2.3+
meetingExpireIfNoUserJoinedInMinutes Number 5 Beëindig de vergadering als niemand binnen dit aantal minuten deelneemt. BBB 2.5+
meetingExpireWhenLastUserLeftInMinutes Number 1 Beëindig de vergadering X minuten nadat de laatste gebruiker vertrekt. 0 = uitgeschakeld. BBB 2.5+
meetingKeepEvents Boolean false Bewaar gebeurtenissen, ook als de vergadering niet wordt opgenomen. BBB 2.3+
learningDashboardCleanupDelayInMinutes Number 2 Vertraging voordat het dashboard voor leeranalyses wordt verwijderd. BBB 2.4+
allowRequestsWithoutSession Boolean false Toestaan om deel te nemen zonder een sessiecookie. BBB 2.4.3+

Presentatie

Parameter Type Standaard Beschrijving
preUploadedPresentation String — URL van een presentatiebestand om vooraf te uploaden. BBB 2.7.2+
preUploadedPresentationName String — Naam voor de vooraf geüploade presentatie. BBB 2.7.2+
preUploadedPresentationOverrideDefault Boolean true Onderdruk de standaardpresentatie (default.pdf). BBB 2.5+
maxNumPages Number 200 Maximumaantal pagina's per presentatie. BBB 3.0.2+
presentationUploadExternalUrl String — URL van een externe bestandskiezer-applicatie. BBB 2.6+
presentationUploadExternalDescription String — Beschrijving van de externe uploadapplicatie. BBB 2.6+
presentationConversionCacheEnabled Boolean — Presentatiecache inschakelen bij gebruik van S3-opslag. BBB 3.0.2+

Gedeelde notities

Parameter Type Standaard Beschrijving
sharedNotesEditor Removed in 4.0 String etherpad Editor die wordt gebruikt voor de gedeelde notities: blockNote of etherpad. De onderstaande parameters voor de initiële inhoud werken alleen met blockNote. BBB 3.0.25+
sharedNotesInitialContentJsonUrl String — HTTPS-URL waarvan de initiële inhoud van de gedeelde notities wordt opgehaald (BlockNote JSON-document). Begrensd door maxSharedNotesInitialContentUrlPayloadSize (standaard 1024 KiB) met een time-out van 6 seconden; overschrijdingen leiden zonder melding tot lege notities. BBB 3.0.25+
sharedNotesInitialContentMarkdown String — Onbewerkte Markdown die als initiële inhoud van de gedeelde notities wordt gebruikt. sharedNotesInitialContentMarkdownUrl heeft voorrang op deze waarde. BBB 3.0.33+
sharedNotesInitialContentMarkdownUrl String — HTTPS-URL waarvan Markdown voor de initiële inhoud van de gedeelde notities wordt opgehaald. Heeft voorrang op de inlineparameter en de POST-module. BBB 3.0.33+

Opname

Parameter Type Standaard Beschrijving
notifyRecordingIsOn Boolean false Toon een modaal dialoogvenster voor toestemming voor opname. BBB 2.6+
notifyRecordingAppend String — Optionele platte tekst die aan het dialoogvenster met de opnamemelding wordt toegevoegd. Wordt alleen getoond met notifyRecordingIsOn=true; HTML wordt als tekst weergegeven. BBB 3.0.36+

Whiteboard

Parameter Type Standaard Beschrijving
multiUserWhiteboardEnabled Boolean — Automatisch whiteboardtoegang inschakelen voor alle gebruikers. Standaard true in breakout rooms. BBB 3.0.20+

Plug-ins

Parameter Type Standaard Beschrijving
pluginManifests JSON — Lijst met pluginmanifests voor de sessie. BBB 3.0+
pluginManifestsFetchUrl String — URL van een JSON-bestand met plugin-manifest-URL's. BBB 3.0.8+

Breakoutruimtes

De parameters isBreakout, parentMeetingID, sequence en freeJoin beschrijven een breakoutroom en worden alleen gebruikt wanneer de breakoutroom zelf wordt aangemaakt (BigBlueButton doet dit intern). De overige parameters in deze tabel worden ingesteld voor de hoofdvergadering en zijn van toepassing op de bijbehorende breakoutrooms.

Parameter Type Standaard Beschrijving
isBreakout Boolean — Moet true zijn voor breakout rooms.
parentMeetingID String — Vergaderings-ID van de hoofdvergadering (vereist voor breakout rooms).
sequence Number — Volgnummer van de breakout room (vereist voor breakout rooms).
freeJoin Boolean — Sta deelnemers toe om vrij hun breakout room te kiezen.
breakoutRoomsPrivateChatEnabled Boolean true Privéchat inschakelen in breakout rooms.
breakoutRoomsRecord Boolean false Breakout rooms opnemen.
breakoutRoomsCaptureSlides Boolean false Leg dia's uit breakout rooms vast wanneer ze eindigen.
breakoutRoomsCaptureNotes Boolean false Leg notities uit breakout rooms vast wanneer ze eindigen.
breakoutRoomsCaptureSlidesFilename String — Bestandsnaam voor vastgelegde dia's.
breakoutRoomsCaptureNotesFilename String — Bestandsnaam voor vastgelegde notities.
groups JSON — Vooraf gedefinieerde groepsindelingen als een JSON-array.

Formaat voor groups:

[
  {"id": "1", "name": "Group A", "roster": ["userId1", "userId2"]},
  {"id": "2", "name": "Group B", "roster": ["userId3"]},
  {"id": "3", "roster": []}
]

Overschrijving van clientinstellingen

Parameter Type Standaard Beschrijving
allowOverrideClientSettingsOnCreateCall Boolean false Serverinstelling in bbb-web.properties (geen create-parameter) die de clientSettingsOverride-module in de POST-body inschakelt. BBB 3.0+
clientSettingsOverride JSON — Overschrijft clientinstellingen uit settings.yml. Wordt alleen geaccepteerd als XML-module in een application/xml POST-body – niet als query- of formulierparameter. BBB 3.0+
clientSettingsOverrideJsonUrl String — URL van een JSON-bestand met overschrijvingen van clientinstellingen. Werkt met gewone GET-verzoeken, vereist geen instelling aan de serverzijde en heeft voorrang op de clientSettingsOverride-module. BBB 3.0.25+

De parameter clientSettingsOverride is standaard uitgeschakeld om veiligheidsredenen. De waarden ervan hebben een hogere prioriteit dan server-side configuratie, en de POST-body wordt niet beschermd door de checksum.

Voorbeeld als XML in de POST-body:

<modules>
  <module name="clientSettingsOverride">
    <![CDATA[
    {
      "public": {
        "app": {
          "clientTitle": "My Conference",
          "helpLink": "https://api-guide.bbbserver.com/help"
        }
      }
    }
    ]]>
  </module>
</modules>

Bruggen

Parameter Type Standaard Beschrijving
cameraBridge String bbb-webrtc-sfu Mediabridge die voor webcamstreams wordt gebruikt: bbb-webrtc-sfu of livekit. BBB 3.0+
screenShareBridge String bbb-webrtc-sfu Mediabridge die voor schermdeling wordt gebruikt: bbb-webrtc-sfu of livekit. BBB 3.0+
audioBridge String bbb-webrtc-sfu Mediabridge die voor audio wordt gebruikt: bbb-webrtc-sfu, livekit of freeswitch. BBB 3.0+

Deze parameters overschrijven de serverbrede bridge-instellingen voor één vergadering.

Metaparameters

Willekeurige metadata kunnen worden doorgegeven als meta_<key>=<value>. Sommige metaparameters hebben een speciale betekenis:

Metaparameter Beschrijving
meta_endCallbackUrl URL voor een GET-callback wanneer de vergadering eindigt. Parameters: meetingID, recordingmarks.
meta_bbb-recording-ready-url URL voor een POST-callback wanneer de opname gereed is (JWT-ondertekend).
meta_analytics-callback-url URL voor een POST-callback met analysedata aan het einde van de vergadering (JSON).
meta_bbb-anonymize-chat Anonimiseer afzenders van chatberichten in opnames (alleen deelnemers).
meta_bbb-anonymize-chat-moderators Anonimiseer afzenders van chatberichten in opnames (inclusief moderatoren).

Naast meta_*-parameters worden ook plugin_*-parameters ondersteund. Deze worden verwerkt als pluginmetadata en kunnen placeholders in plugin-manifest-URL's vervangen. BBB 3.0.10+

Voorbeeldverzoek

GET https://api-guide.bbbserver.com/bigbluebutton/api/create?name=Demo&meetingID=replace-with-meeting-id&attendeePW=replace-with-password&moderatorPW=replace-with-password&checksum=replace-with-checksum

Voorbeeldrespons

<response>
  <returncode>SUCCESS</returncode>
        <meetingID>replace-with-meeting-id</meetingID>
    <internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
  <parentMeetingID>bbb-none</parentMeetingID>
        <attendeePW>replace-with-password</attendeePW>
        <moderatorPW>replace-with-password</moderatorPW>
  <createTime>1715261728123</createTime>
  <voiceBridge>70066</voiceBridge>
  <dialNumber>613-555-1234</dialNumber>
  <createDate>Thu May 09 13:35:28 UTC 2024</createDate>
  <hasUserJoined>false</hasUserJoined>
  <duration>0</duration>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
  <messageKey></messageKey>
  <message></message>
</response>

Als er al een vergadering met dezelfde ID bestaat, bevat het antwoord een waarschuwing voor een duplicaat:

<response>
  <returncode>SUCCESS</returncode>
    <meetingID>replace-with-meeting-id</meetingID>
  <!-- ... same fields ... -->
  <messageKey>duplicateWarning</messageKey>
  <message>This conference was already in existence...</message>
</response>

Presentaties uploaden via POST-body

Presentaties kunnen worden ingediend als een XML-body met het POST-verzoek:

<modules>
  <module name="presentation">
        <document url="https://api-guide.bbbserver.com/files/slides.pdf" filename="slides.pdf"
              downloadable="true" removable="false" current="true"/>
        <document url="https://api-guide.bbbserver.com/files/extras.pdf" filename="extras.pdf"/>
    <document name="inline.pdf">
      JVBERi0xLjQK... (Base64-encoded content)
    </document>
  </module>
</modules>

Attributen per <document>-element:

Attribuut Type Standaard Beschrijving
url String — URL van het externe bestand.
filename String — Bestandsnaam inclusief de extensie. Vereist wanneer het URL-pad niet eindigt op een bestandsnaam met een extensie; anders wordt het document overgeslagen.
name String — Naam voor in Base64 ingesloten documenten.
downloadable Boolean false Sta gebruikers toe de presentatie te downloaden.
removable Boolean true Sta gebruikers toe de presentatie te verwijderen.
current Boolean — Deze presentatie wordt als eerste geladen.

Wanneer meerdere documenten worden opgegeven, wordt het eerste in de client geladen terwijl de overige op de achtergrond worden geconverteerd.

bbbserver.de Notities

Aanvullende parameter

Parameter Type Standaard Beschrijving
deactivateBbbserverDefaultChatTexts Boolean false Wanneer ingesteld op false (standaard), voegt bbbserver.de automatisch chatteksten in (inbelnummers, hostingmelding). Je eigen teksten welcome en moderatorOnlyMessage worden hierna toegevoegd. Stel in op true om de teksten van bbbserver.de te onderdrukken (white labelling).

Capaciteitsreservering

Op bbbserver.de hebben de parameters maxParticipants en duration een speciale betekenis en gedragen ze zich anders dan in standaard BigBlueButton.

Bij het aanmaken van een vergadering reserveert bbbserver.de hardwarecapaciteit:

  • Het opgegeven aantal deelnemers wordt gegarandeerd en voor de opgegeven duur op een server gereserveerd.
  • De gereserveerde capaciteit wordt afgetrokken van je geboekte quotum voor gelijktijdige verbindingen.
  • Als dit niet wordt opgegeven, gelden de standaardwaarden: 5 deelnemers en 60 minuten (instelbaar in het beheerpaneel onder Integrations & API → Integration API).
  • Nadat de duur is verstreken, blijft de vergadering actief, maar wordt er geen capaciteit meer gereserveerd. bbbserver.de kan de vergadering automatisch beëindigen als een nieuwe vergadering die capaciteit nodig heeft.
  • De parameter duration beëindigt geen vergaderingen. In tegenstelling tot standaard BBB moet je een end API-aanroep versturen om een vergadering na een bepaalde tijd te beëindigen.

Sinds BBB 3.0 zijn de parameters attendeePW en moderatorPW verouderd. Gebruik in plaats daarvan de parameter role op het endpoint join om rollen toe te wijzen.

Veelgestelde vragen

De server retourneert de gegevens van de bestaande vergadering in plaats van een nieuwe aan te maken. Het antwoord bevat een berichtsleutel duplicateWarning om dit aan te geven.

Nee. Sinds BBB 3.0 zijn deze wachtwoorden verouderd en worden ze automatisch gegenereerd. Gebruik de parameter role op het endpoint join om rollen voor deelnemers of moderators toe te wijzen.

Verstuur een POST-verzoek met een XML-body die een element modules/module bevat met documentvermeldingen. Elk document kan verwijzen naar een externe URL of Base64-gecodeerde bestandsdata bevatten.

meta_endCallbackUrl is een metaparameter die kan worden doorgegeven aan de client en de opnamemetadata. meetingEndedURL is een callback aan de serverzijde die intern blijft en niet aan clients wordt blootgesteld. Daarom is dit de aanbevolen optie voor URL's die geheime tokens bevatten.

Wanneer je een vergadering aanmaakt, reserveert bbbserver.de hardwarecapaciteit op basis van de waarden maxParticipants en duration. De gereserveerde slots worden afgetrokken van je quota voor gelijktijdige verbindingen. Nadat de duur is verstreken, loopt de vergadering door, maar is deze niet langer beschermd tegen beëindiging als elders capaciteit nodig is.

Ja, door allowOverrideClientSettingsOnCreateCall op true te zetten en een clientSettingsOverride JSON mee te geven in de POST-body. Dit is standaard uitgeschakeld om veiligheidsredenen, aangezien de POST-body niet door de checksum wordt gedekt.