You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.
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
getMeetingInfoandgetRecordingsresponses. - 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 identifierrecordingmarks — 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 is only sent if the meeting events are kept: pass meetingKeepEvents=true in the create call or set defaultKeepEvents=true on the server (default: false). The exact schema of the analytics data object may change between versions.
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.
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
updateRecordingsendpoint 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
signed_parameters holding a JWT signed with HS256 using the server shared secret. Its payload contains meeting_id (the external meeting ID) and record_id (the recording ID).