🔌 BigBlueButton API — Quick Reference

📖 Official documentation: https://docs.bigbluebutton.org/development/api/

⚠️ Heads-up: This is a concise, developer-friendly summary of the official docs (BigBlueButton HTTP API). Always verify parameters against your server version.

🔗 Base URL

The API is exposed over HTTP(S) and returns XML.

https://<your-bbb-host>/bigbluebutton/api/

Each call is GET with query params plus a checksum.

🔐 Authentication (checksum)

Every request must include a SHA-1 checksum:

checksum = sha1( apiMethod + queryString + sharedSecret )

apiMethod is the path method name (e.g., create, join).
queryString is the exact URL query portion (sorted & encoded as sent).
sharedSecret is your BBB secret from bbb-conf --secret (or admin panel).

Append &checksum=<checksum> to the request.

🧱 Common types & params

meetingID (string, required for most) — unique per meeting.
name (string) — display name of meeting (on create).
moderatorPW, attendeePW (string) — passwords for roles.
fullName (string) — user display name (on join).
userID (string) — optional external user ID.
record (boolean: true|false) — enable recording (on create).
duration (minutes) — auto-end time (0 = unlimited).
maxParticipants (int) — room capacity limit.
welcome, logoutURL, bannerText, bannerColor, etc.
meta_* — custom metadata pairs attached to meeting & recordings.

Responses are XML <response>... with a <returncode>SUCCESS|FAILED</returncode> and optionally <messageKey> / <message> on errors.

🚀 Core API methods

Below are the most used endpoints. All are GET on /bigbluebutton/api/<method>.

1) `create` — Create a meeting

Required: meetingID, name
Common: moderatorPW, attendeePW, record, duration, welcome, logoutURL, maxParticipants, meta_*

/bigbluebutton/api/create?name=Demo&meetingID=demo-123&moderatorPW=mp&attendeePW=ap&checksum=...

Success: XML containing meeting info and passwords.
If the meeting already exists, create is idempotent for same meetingID (updates some fields).

2) `join` — Get the join URL for a user

Required: meetingID, fullName, one of password (moderatorPW or attendeePW)
Useful: userID, avatarURL, userdata-*, clientSettingsOverride

/bigbluebutton/api/join?fullName=Alice&meetingID=demo-123&password=mp&checksum=...

The server responds with an HTTP redirect to the HTML5 client. You typically build and open this URL in your app.

3) `isMeetingRunning` — Boolean status

Required: meetingID

/bigbluebutton/api/isMeetingRunning?meetingID=demo-123&checksum=...

Response: <running>true|false</running>.

4) `getMeetingInfo` — Live details for one meeting

Required: meetingID, password (mod or attendee)

/bigbluebutton/api/getMeetingInfo?meetingID=demo-123&password=mp&checksum=...

Response: participant list, recording flag, start time, voice bridge, etc.

5) `getMeetings` — List meetings

No required params.

/bigbluebutton/api/getMeetings?checksum=...

Response: <meetings><meeting>...</meeting>...</meetings>.

6) `end` — Terminate a meeting

Required: meetingID, password (must be moderatorPW)

/bigbluebutton/api/end?meetingID=demo-123&password=mp&checksum=...

Ends the running session and disconnects users.

7) Recording management

getRecordings?meetingID=<id> — list recordings (filter by meetingID or recordID).
publishRecordings?recordID=<id>&publish=true|false — show/hide in UI.
deleteRecordings?recordID=<id> — delete.
updateRecordings?recordID=<id>&meta_name=value — update metadata (e.g., title).

All require a valid checksum and return XML with status per record.

🧩 Client settings override (per-join)

Use clientSettingsOverride on the join call to tweak HTML5 client behavior for that user/session (server must support it).

Example (URL-encoded JSON):

clientSettingsOverride=%7B%22uiSettings%22%3A%7B%22hideBrandingArea%22%3Atrue%7D%7D

Joined into:

/bigbluebutton/api/join?fullName=Alice&meetingID=demo-123&password=ap&clientSettingsOverride=...&checksum=...

For global defaults, use server configs; for per-meeting defaults, pass options on create.

🔁 Typical flows

💼 Create + Join (host)

create(meetingID=demo-123, moderatorPW=mp, attendeePW=ap, record=true)
Build join(..., password=mp) URL for the host and open it in a browser.

👥 Invite participants

Send them your app’s “Join as attendee” link that resolves to join(..., password=ap).

📼 Recording lifecycle

Enable record=true on create.
Later, use getRecordings → publishRecordings/deleteRecordings/updateRecordings.

🧪 cURL examples

# 1) Create
BASE="https://bbb.example.com/bigbluebutton/api"
QS="name=Demo&meetingID=demo-123&moderatorPW=mp&attendeePW=ap"
CS=$(printf "create%s%s" "$QS" "$SECRET" | sha1sum | awk '{print $1}')
curl "$BASE/create?$QS&checksum=$CS"

# 2) Join (moderator)
QS2="fullName=Alice&meetingID=demo-123&password=mp"
CS2=$(printf "join%s%s" "$QS2" "$SECRET" | sha1sum | awk '{print $1}')
echo "$BASE/join?$QS2&checksum=$CS2"

💻 Code samples

Node.js (axios) 🟩

import crypto from "node:crypto";
import axios from "axios";

const BASE = "https://bbb.example.com/bigbluebutton/api";
const SECRET = process.env.BBB_SECRET;

function sign(method, qs) {
  const raw = method + qs + SECRET;
  return crypto.createHash("sha1").update(raw).digest("hex");
}

async function createMeeting() {
  const qs = "name=Demo&meetingID=demo-123&moderatorPW=mp&attendeePW=ap&record=true";
  const url = `${BASE}/create?${qs}&checksum=${sign("create", qs)}`;
  const { data } = await axios.get(url);
  console.log(data);
}

Python (requests) 🐍

import hashlib, requests, os

BASE = "https://bbb.example.com/bigbluebutton/api"
SECRET = os.getenv("BBB_SECRET")

def sign(method, qs):
    return hashlib.sha1((method + qs + SECRET).encode("utf-8")).hexdigest()

qs = "fullName=Alice&meetingID=demo-123&password=mp"
url = f"{BASE}/join?{qs}&checksum={sign('join', qs)}"
r = requests.get(url, allow_redirects=False)
print(r.status_code, r.headers.get("location"))

PHP (cURL) 🐘

<?php
$BASE = "https://bbb.example.com/bigbluebutton/api";
$SECRET = getenv("BBB_SECRET");

function sign($method, $qs, $secret) {
  return sha1($method . $qs . $secret);
}

$qs = "meetingID=demo-123";
$checksum = sign("isMeetingRunning", $qs, $SECRET);
$url = "$BASE/isMeetingRunning?$qs&checksum=$checksum";

$xml = file_get_contents($url);
echo $xml;

### ASP.NET (C# HttpClient) 🟦
```csharp
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;

string BASE = "https://bbb.example.com/bigbluebutton/api";
string SECRET = Environment.GetEnvironmentVariable("BBB_SECRET");

string Sign(string method, string qs) {
  using var sha = SHA1.Create();
  var hash = sha.ComputeHash(Encoding.UTF8.GetBytes(method + qs + SECRET));
  var sb = new StringBuilder();
  foreach (var b in hash) sb.Append(b.ToString("x2"));
  return sb.ToString();
}

var qs = "meetingID=demo-123";
var url = $"{BASE}/getRecordings?{qs}&checksum={Sign("getRecordings", qs)}";
var xml = await new HttpClient().GetStringAsync(url);
Console.WriteLine(xml);

🛡️ Security & deployment notes

Prefer HTTPS; treat the shared secret like a password.
Only your backend should know BBB_SECRET. Never expose it directly to browsers.
Consider IP allow-listing, WAF, and rate-limit proxies in front of /bigbluebutton/api/.
Validate all user input you inject into API query strings.

❗ Common errors

messageKey	Why it happens
`checksumError`	Wrong checksum or param order mismatch.
`missingParameter`	Required param missing (e.g., meetingID).
`invalidMeetingIdentifier`	Bad/unknown `meetingID`.
`notFound`	Meeting/recording doesn’t exist.
`noSuchRecording`	Recording ID is invalid.

Check <message> in the XML for human-readable details.

📚 See also

🌐 Official API docs: https://docs.bigbluebutton.org/development/api/
getDefaultConfigXML / setConfigXML — manage config tokens (older approach).
clientSettingsOverride — per-join JSON override for the HTML5 client.
Breakouts & LiveKit settings — controlled via server config (not core HTTP API).

For full details, examples, and version-specific differences, consult the official BigBlueButton docs that match your server version.

🔗 Base URL​

🔐 Authentication (checksum)​

🧱 Common types & params​

🚀 Core API methods​

1) create — Create a meeting​

2) join — Get the join URL for a user​

3) isMeetingRunning — Boolean status​

4) getMeetingInfo — Live details for one meeting​

5) getMeetings — List meetings​

6) end — Terminate a meeting​

7) Recording management​

🧩 Client settings override (per-join)​

🔁 Typical flows​

💼 Create + Join (host)​

👥 Invite participants​

📼 Recording lifecycle​

🧪 cURL examples​

💻 Code samples​

Node.js (axios) 🟩​

Python (requests) 🐍​

PHP (cURL) 🐘​

🛡️ Security & deployment notes​

❗ Common errors​

📚 See also​