Hoofdstuk 18

Meta-parameters & callbacks

Metaparameters zijn vrij definieerbare sleutel-waardeparen die je doorgeeft bij het aanmaken van een vergadering. Hiermee kun je aangepaste metadata koppelen, geautomatiseerde callbacks bij specifieke gebeurtenissen activeren, anonimisering van opnames regelen en de herkomst van een vergadering documenteren voor LMS-integraties.

Hoe meta-parameters werken

Meta-parameters worden doorgegeven in de API-aanroep create volgens de naamgevingsconventie meta_=. Je kunt een onbeperkt aantal meta-parameters aan één enkele vergadering koppelen. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Meta-parameters worden geretourneerd in de responses van getMeetingInfo en getRecordings.
  • Opnames kunnen worden gefilterd op meta-waarden met getRecordings?meta_=.
  • Opnamemetadata kunnen achteraf worden bijgewerkt via updateRecordings.

Callback-meta-parameters

Bepaalde metaparameters hebben een speciale betekenis en activeren HTTP-callbacks wanneer specifieke gebeurtenissen optreden. Hiermee kan je applicatie automatisch reageren op gebeurtenissen in de levenscyclus van een vergadering.

meta_endCallbackUrl

Activeert een HTTP GET-verzoek naar de opgegeven URL wanneer de vergadering eindigt. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Eigenschap Waarde
HTTP-methode GET
Trigger Wanneer de vergadering eindigt
Callback Parameters meetingID — de vergaderingsidentificatie
recordingmarks — true als de opname markeringen bevat, anders false

Voorbeeld callbackverzoek: 

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Activeert een HTTP POST-verzoek wanneer de opname volledig is verwerkt en gepubliceerd. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Eigenschap Waarde
HTTP-methode POST
Trigger Wanneer de opname volledig is verwerkt en gepubliceerd
Beveiliging Parameters zijn met JWT ondertekend (JSON Web Token)
POST-body Bevat ondertekende gegevens met opname-informatie

Verwar deze callback niet met endCallbackUrl. Het verwerken van opnames kan aanzienlijke tijd kosten nadat de vergadering is geëindigd. De recording-ready-callback wordt pas uitgevoerd zodra de verwerking is voltooid.

meta_analytics-callback-url

Activeert een HTTP POST-verzoek met geaggregeerde analyticsgegevens nadat de vergadering is geëindigd. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Eigenschap Waarde
HTTP-methode POST
Trigger Nadat de vergadering is geëindigd (post-events hook)
Authenticatie JWT-token verzonden als Authorization: Bearer-header (HS512, ondertekend met het gedeelde geheim van BBB, 24 uur geldig)
Bodyformaat JSON-object met daarin version, meeting_id, internal_meeting_id, data
Inhoud van de gegevens Deelnameduur, activiteitsstatistieken, chatgebruik en andere geaggregeerde vergadergebeurtenissen

De analytics-callback-URL is afkomstig uit de BigBlueButton-codebasis en is niet volledig gedocumenteerd in de officiële API-documentatie. Het exacte schema van het analyticsgegevensobject is niet gestandaardiseerd en kan per versie veranderen. undocumented

Let op het verschil in levering van JWT: analytics-callback-url verzendt de JWT als een HTTP Authorization-header, terwijl bbb-recording-ready-url de JWT rechtstreeks opneemt in de POST-body.

Parameters voor anonimisering van opnames

Deze meta-parameters bepalen of de namen van chatafzenders in verwerkte opnames worden geanonimiseerd. Ze zijn nuttig voor naleving van privacy- en gegevensbeschermingsvereisten.

Parameter Type Standaard Beschrijving
meta_bbb-anonymize-chat Boolean false Anonimiseert afzenders van chatberichten in verwerkte opnames. Heeft alleen effect op berichten van kijkers (niet-moderators). Namen van moderators blijven zichtbaar.
meta_bbb-anonymize-chat-moderators Boolean false Anonimiseert daarnaast ook de afzenders van chatberichten van moderators in opnames. Vereist doorgaans ook dat meta_bbb-anonymize-chat=true is ingesteld.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

De anonimiseringsparameters worden slechts kort genoemd in de officiële API-documentatie. Hun gedrag is afgeleid van de BigBlueButton-broncode. undocumented

LMS-integratieparameters

Veel LMS-plugins stellen automatisch metaparameters in om de herkomst van een vergadering te documenteren. Deze zijn informatief en hebben geen invloed op het gedrag van de vergadering, maar zijn nuttig voor auditing en rapportage.

Parameter Voorbeeld Beschrijving
meta_bbb-origin greenlight, moodle De bronapplicatie die de vergadering heeft aangemaakt.
meta_bbb-origin-version v3.1.0 Versie van de bronapplicatie.
meta_bbb-origin-server-name api-guide.bbbserver.com Hostnaam van de bronapplicatie.
meta_bbb-context Course: Computer Science Contextinformatie zoals de cursusnaam.
meta_bbb-context-id course-42 Contextidentificatie voor programmatisch gebruik.

Best practices voor aangepaste meta-parameters

  • Gebruik beschrijvende sleutelnamen (bijv. meta_department, meta_project) die duidelijk het doel van de waarde aangeven.
  • Gebruik URL-codering voor waarden die speciale tekens, spaties of niet-ASCII-tekens bevatten.
  • Gebruik metaparameters voor integratie met externe systemen zoals CRMs, leerplatforms of analyticsdashboards.
  • Werk metadata van opnames achteraf bij met het endpoint updateRecordings om metadata toe te voegen of te corrigeren.

Combineer meta-parameters met filtering via getRecordings om krachtige zoek- en categorisatieworkflows voor je opnames op te bouwen. Filter bijvoorbeeld op meta_department=engineering om alleen opnames van engineeringvergaderingen op te halen.

Veelgestelde vragen

Er is geen harde limiet voor het aantal meta-parameters. Omdat ze echter als URL-queryparameters worden doorgegeven, moet je binnen praktische limieten voor URL-lengte blijven (meestal 2.000 tot 8.000 tekens, afhankelijk van de configuratie van de webserver).

Metaparameters die tijdens de create-aanroep zijn ingesteld, kunnen niet worden gewijzigd terwijl de vergadering loopt. Metadata van opnames kan echter na verwerking worden bijgewerkt via het updateRecordings-endpoint.

De endCallbackUrl wordt direct geactiveerd wanneer de vergadering eindigt, met een eenvoudig GET-verzoek. De bbb-recording-ready-url wordt veel later geactiveerd, pas nadat de opname volledig is verwerkt en gepubliceerd, en gebruikt een met JWT ondertekend POST-verzoek.

De details van de JWT-ondertekening zijn niet volledig gespecificeerd in de officiële documentatie. Op basis van de BigBlueButton-broncode wordt de JWT ondertekend met het gedeelde geheim van de server. De exacte claims en het algoritme moeten worden gecontroleerd voor jouw specifieke BigBlueButton-versie.

De meeste metaparameters zijn puur informatief en veranderen niet hoe de vergadering werkt. De uitzonderingen zijn callback-URL's, die HTTP-verzoeken bij gebeurtenissen activeren, en anonimiseringsparameters, die van invloed zijn op hoe opnames worden verwerkt.

Ja. Sleutels van metaparameters worden behandeld als hoofdlettergevoelige strings. Bijvoorbeeld, meta_Department en meta_department worden opgeslagen als twee afzonderlijke parameters. Gebruik consistente hoofdlettergebruik in je integratie om duplicaten te voorkomen.