Chapter 18

Meta-Parameters & Callbacks

Meta parameters are freely definable key-value pairs that you pass when creating a meeting. They allow you to attach custom metadata, trigger automated callbacks on specific events, control recording anonymization, and document the origin of a meeting for LMS integrations.

How Meta Parameters Work

Meta parameters are passed in the create API call using the naming convention meta_<key>=<value>. You can attach any number of meta parameters to a single meeting. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Meta parameters are returned in getMeetingInfo and getRecordings responses.
  • Recordings can be filtered by meta values using getRecordings?meta_<key>=<value>.
  • Recording metadata can be updated after the fact via updateRecordings.

Callback Meta Parameters

Certain meta parameters have special meaning and trigger HTTP callbacks when specific events occur. These allow your application to react automatically to meeting lifecycle events.

meta_endCallbackUrl

Triggers an HTTP GET request to the specified URL when the meeting ends. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Property Value
HTTP Method GET
Trigger When the meeting ends
Callback Parameters meetingID — the meeting identifier
recordingmarks — true if the recording contains marks, otherwise false

Example callback request: 

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

meta_bbb-recording-ready-url

Triggers an HTTP POST request when the recording has been fully processed and published. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Property Value
HTTP Method POST
Trigger When the recording is fully processed and published
Security Parameters are JWT-signed (JSON Web Token)
POST Body Contains signed data with recording information

Do not confuse this callback with endCallbackUrl. Recording processing can take a significant amount of time after the meeting has ended. The recording-ready callback fires only once processing is complete.

meta_analytics-callback-url

Triggers an HTTP POST request with aggregated analytics data after the meeting ends. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Property Value
HTTP Method POST
Trigger After the meeting ends (post-events hook)
Authentication JWT token sent as Authorization: Bearer header (HS512, signed with the BBB shared secret, valid for 24 hours)
Body Format JSON object containing version, meeting_id, internal_meeting_id, data
Data Contents Participation duration, activity statistics, chat usage, and other aggregated meeting events

The analytics callback URL is sourced from the BigBlueButton codebase and is not fully documented in the official API documentation. The exact schema of the analytics data object is not standardized and may change between versions. undocumented

Note the difference in JWT delivery: analytics-callback-url sends the JWT as an HTTP Authorization header, while bbb-recording-ready-url includes the JWT directly in the POST body.

Recording Anonymization Parameters

These meta parameters control whether chat sender names are anonymized in processed recordings. They are useful for privacy compliance and data protection requirements.

Parameter Type Default Description
meta_bbb-anonymize-chat Boolean false Anonymizes chat message senders in processed recordings. Only affects viewer (non-moderator) messages. Moderator names remain visible.
meta_bbb-anonymize-chat-moderators Boolean false Additionally anonymizes moderator chat message senders in recordings. Typically requires meta_bbb-anonymize-chat=true to be set as well.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

The anonymization parameters are only briefly mentioned in the official API documentation. Their behavior is derived from the BigBlueButton source code. undocumented

LMS Integration Parameters

Many LMS plugins automatically set meta parameters to document the origin of a meeting. These are informational and do not affect meeting behavior, but they are useful for auditing and reporting.

Parameter Example Description
meta_bbb-origin greenlight, moodle The source application that created the meeting.
meta_bbb-origin-version v3.1.0 Version of the source application.
meta_bbb-origin-server-name api-guide.bbbserver.com Hostname of the source application.
meta_bbb-context Course: Computer Science Context information such as course name.
meta_bbb-context-id course-42 Context identifier for programmatic use.

Best Practices for Custom Meta Parameters

  • Use descriptive key names (e.g. meta_department, meta_project) that clearly indicate the purpose of the value.
  • URL-encode values that contain special characters, spaces, or non-ASCII characters.
  • Use meta parameters for integration with external systems such as CRMs, learning platforms, or analytics dashboards.
  • Update recording metadata after the fact using the updateRecordings endpoint to add or correct metadata.

Combine meta parameters with getRecordings filtering to build powerful search and categorization workflows for your recordings. For example, filter by meta_department=engineering to retrieve only recordings from engineering meetings.

Frequently Asked Questions

There is no hard limit on the number of meta parameters. However, since they are passed as URL query parameters, you should stay within practical URL length limits (typically 2,000 to 8,000 characters depending on the web server configuration).

Meta parameters set during the create call cannot be changed while the meeting is running. However, recording metadata can be updated after processing using the updateRecordings endpoint.

The endCallbackUrl fires immediately when the meeting ends, using a simple GET request. The bbb-recording-ready-url fires much later, only after the recording has been fully processed and published, and uses a JWT-signed POST request.

The JWT signing details are not fully specified in the official documentation. Based on the BigBlueButton source code, the JWT is signed using the server shared secret. The exact claims and algorithm should be verified against your specific BigBlueButton version.

Most meta parameters are purely informational and do not change how the meeting operates. The exceptions are callback URLs, which trigger HTTP requests on events, and anonymization parameters, which affect how recordings are processed.

Yes. Meta parameter keys are treated as case-sensitive strings. For example, meta_Department and meta_department would be stored as two separate parameters. Use consistent casing in your integration to avoid duplicates.