bbb-api-js

A TypeScript/JavaScript client library for interacting with the BigBlueButton API.

Features

• Full TypeScript support with comprehensive type definitions
• Promise-based API for async/await usage
• Automatic checksum generation with multiple hash algorithm support (SHA-1, SHA-256, SHA-384, SHA-512)
• Built-in XML parsing and response handling
• Custom error classes for better error handling
• Zero runtime dependencies (except axios and xml2js)

Installation

npm install bbb-api-js

Quick Start

import { BBBClient } from 'bbb-api-js';

// Initialize the client
const client = new BBBClient({
  serverUrl: 'https://bbb.example.com/bigbluebutton/api',
  secret: 'your-shared-secret'
});

// Create a meeting
const meeting = await client.create({
  meetingID: 'my-meeting-123',
  name: 'My First Meeting',
  attendeePW: 'attendee-password',
  moderatorPW: 'moderator-password',
  record: true
});

// Generate a join URL for a moderator
const joinUrl = client.join({
  fullName: 'John Doe',
  meetingID: 'my-meeting-123',
  password: meeting.moderatorPW
});

console.log('Join the meeting at:', joinUrl);

API Reference

Important Notes

All parameters and response fields documented below are part of the official BigBlueButton API specification unless otherwise noted. This library is a direct wrapper around the BBB API and does not add or modify any functionality.

Response Structure: All API responses include a returncode field with either 'SUCCESS' or 'FAILED'. This field is preserved in all response objects returned by this library, maintaining compatibility with the actual BBB API response structure.

Constructor

new BBBClient(config)

Creates a new BigBlueButton API client.

Parameters:

• config.serverUrl (string, required): Base URL of your BigBlueButton API endpoint
• config.secret (string, required): Shared secret from your BBB server
• config.hashAlgorithm (string, optional): Hash algorithm for checksums. Options: 'sha1', 'sha256' (default), 'sha384', 'sha512'

const client = new BBBClient({
  serverUrl: 'https://bbb.example.com/bigbluebutton/api',
  secret: 'your-shared-secret',
  hashAlgorithm: 'sha256' // optional
});

Methods

create(params): Promise<CreateMeetingResponse>

Creates a new meeting.

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#create

Required Parameters:

• meetingID (string): Unique identifier for the meeting
• name (string): Display name for the meeting

Optional Parameters:

• attendeePW (string): Password for attendees
• moderatorPW (string): Password for moderators
• welcome (string): Welcome message displayed when users join
• dialNumber (string): Dial-in number for voice conference
• voiceBridge (string): Voice bridge number
• maxParticipants (number): Maximum number of participants
• logoutURL (string): URL to redirect users when meeting ends
• record (boolean): Whether meeting is recorded on start
• duration (number): Duration of meeting in minutes
• isBreakout (boolean): Whether this is a breakout room
• parentMeetingID (string): Parent meeting ID for breakout rooms
• sequence (number): Sequence number for breakout rooms
• autoStartRecording (boolean): Whether to auto-start recording
• allowStartStopRecording (boolean): Whether participants can start/stop recording
• webcamsOnlyForModerator (boolean): Whether webcams are shared only with moderators
• logo (string): Logo to display in the client
• copyright (string): Copyright text
• muteOnStart (boolean): Whether to mute on start
• guestPolicy ('ALWAYS_ACCEPT' | 'ALWAYS_DENY' | 'ASK_MODERATOR'): Guest approval policy
• meta_* (string): Additional metadata (key-value pairs with meta_ prefix)

Response Fields:

• returncode ('SUCCESS' | 'FAILED'): API response status
• meetingID (string): Meeting identifier
• internalMeetingID (string): Internal meeting identifier
• parentMeetingID (string, optional): Parent meeting identifier
• attendeePW (string): Attendee password
• moderatorPW (string): Moderator password
• createTime (number): Meeting creation timestamp
• voiceBridge (string): Voice bridge number
• dialNumber (string, optional): Dial-in number
• createDate (string): Meeting creation date
• hasUserJoined (boolean): Whether any user has joined
• duration (number): Meeting duration
• hasBeenForciblyEnded (boolean): Whether meeting was forcibly ended
• message (string, optional): Additional message (e.g., duplicate warning)
• messageKey (string, optional): Message key for localization

const meeting = await client.create({
  meetingID: 'meeting-123',
  name: 'Team Standup',
  attendeePW: 'ap',
  moderatorPW: 'mp',
  welcome: 'Welcome to the meeting!',
  record: true,
  duration: 60,
  meta_description: 'Daily team standup'
});

console.log('Status:', meeting.returncode);
console.log('Meeting created:', meeting.meetingID);
console.log('Internal ID:', meeting.internalMeetingID);

join(params): string

Generates a join URL for a participant to join a meeting.

Important: This method does NOT make an API call. It only generates the URL that users should navigate to in their browser.

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#join

Required Parameters:

• fullName (string): Display name for the participant
• meetingID (string): Meeting ID to join
• password (string): Attendee or moderator password

Optional Parameters:

• createTime (number): Meeting creation time for validation
• userID (string): Custom user identifier
• webVoiceConf (string): Web voice conference voice bridge
• configToken (string): Configuration token
• defaultLayout (string): Default layout for the user
• avatarURL (string): URL to user's avatar image
• redirect (boolean): Whether to redirect immediately
• clientURL (string): Custom client URL
• joinViaHtml5 (boolean): Join via HTML5 client
• guest (boolean): Whether user is a guest

Returns: Complete join URL as a string

Throws: BBBConfigError if required parameters are missing

// Generate moderator join URL
const modUrl = client.join({
  fullName: 'Jane Smith',
  meetingID: 'meeting-123',
  password: meeting.moderatorPW,
  userID: 'user-456'
});

// Generate attendee join URL
const attendeeUrl = client.join({
  fullName: 'John Doe',
  meetingID: 'meeting-123',
  password: meeting.attendeePW
});

getMeetingInfo(meetingID): Promise<MeetingInfo>

Gets detailed information about a running meeting.

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#getmeetinginfo

Required Parameters:

• meetingID (string): Meeting ID

Response Fields:

• returncode ('SUCCESS' | 'FAILED'): API response status
• meetingName (string): Meeting name
• meetingID (string): Meeting identifier
• internalMeetingID (string): Internal meeting identifier
• createTime (number): Meeting creation timestamp
• createDate (string): Meeting creation date
• voiceBridge (string): Voice bridge number
• dialNumber (string, optional): Dial-in number
• attendeePW (string): Attendee password
• moderatorPW (string): Moderator password
• running (boolean): Whether meeting is currently running
• duration (number): Meeting duration
• hasUserJoined (boolean): Whether any user has joined
• recording (boolean): Whether meeting is being recorded
• hasBeenForciblyEnded (boolean): Whether meeting was forcibly ended
• startTime (number, optional): Meeting start timestamp
• endTime (number, optional): Meeting end timestamp
• participantCount (number): Number of participants
• listenerCount (number): Number of listeners
• voiceParticipantCount (number): Number of voice participants
• videoCount (number): Number of video streams
• maxUsers (number): Maximum users allowed
• moderatorCount (number): Number of moderators
• attendees (Attendee[]): Array of attendee objects
• metadata (Record<string, string>, optional): Meeting metadata
• isBreakout (boolean): Whether this is a breakout room

const info = await client.getMeetingInfo('meeting-123');

console.log('Status:', info.returncode);
console.log('Meeting:', info.meetingName);
console.log('Running:', info.running);
console.log('Participants:', info.participantCount);
console.log('Attendees:', info.attendees.map(a => a.fullName));

endMeeting(meetingID, password): Promise<EndMeetingResponse>

Forcibly ends a meeting and kicks all participants out.

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#end

Required Parameters:

• meetingID (string): Meeting ID
• password (string): Moderator password

Response Fields:

• returncode ('SUCCESS' | 'FAILED'): API response status
• message (string, optional): Response message
• messageKey (string, optional): Message key for localization

const result = await client.endMeeting('meeting-123', 'moderator-password');
console.log('Status:', result.returncode);
console.log('Message:', result.message);

getRecordings(params?): Promise<GetRecordingsResult>

Retrieves recordings from the server.

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#getrecordings

Optional Parameters:

• meetingID (string): Filter by meeting ID (if not provided, returns all recordings)
• recordID (string): Filter by recording ID
• state ('processing' | 'processed' | 'published' | 'unpublished' | 'deleted' | 'any'): Filter by state
• meta_* (string): Metadata filters (key-value pairs with meta_ prefix)

Response Fields:

• returncode ('SUCCESS' | 'FAILED'): API response status
• recordings (Recording[]): Array of recording objects
• message (string, optional): Response message
• messageKey (string, optional): Message key for localization

Recording Object Fields:

• recordID (string): Recording identifier
• meetingID (string): Meeting identifier
• internalMeetingID (string): Internal meeting identifier
• name (string): Recording name
• isBreakout (boolean): Whether from breakout room
• published (boolean): Whether recording is published
• state (string): Recording state
• startTime (number): Recording start timestamp
• endTime (number): Recording end timestamp
• participants (number): Number of participants
• metadata (Record<string, string>, optional): Recording metadata
• playback (object, optional): Playback format information

// Get all recordings
const result = await client.getRecordings();
console.log('Status:', result.returncode);
console.log('Total recordings:', result.recordings.length);

// Get recordings for a specific meeting
const meetingResult = await client.getRecordings({
  meetingID: 'meeting-123'
});

// Get published recordings
const publishedResult = await client.getRecordings({
  state: 'published'
});

meetingResult.recordings.forEach(recording => {
  console.log('Recording:', recording.name);
  console.log('Duration:', recording.endTime - recording.startTime);
  console.log('Participants:', recording.participants);
});

insertDocument(params): Promise<InsertDocumentResponse>

Inserts presentation documents into a running meeting.

Available since BigBlueButton 2.5

Official BBB API Reference: https://docs.bigbluebutton.org/development/api#insertdocument

Required Parameters:

• meetingID (string): Meeting ID to insert documents into
• documents (Document[]): Array of documents to insert (must have at least one)

Document Object Properties:

• url (string, optional): URL of the document (mutually exclusive with content)
• content (string, optional): Base64 encoded document content (mutually exclusive with url)
• filename (string, optional): Filename (useful if URL lacks extension)
• downloadable (boolean, optional): Whether document can be downloaded (default: false)
• removable (boolean, optional): Whether document can be removed (default: true)

Note: The first document in the array will be loaded immediately in the client. Other documents will be processed in the background.

Response Fields:

• returncode ('SUCCESS' | 'FAILED'): API response status
• message (string, optional): Response message
• messageKey (string, optional): Message key for localization

Throws: BBBConfigError if documents array is empty or invalid

// Insert a document from URL
const result = await client.insertDocument({
  meetingID: 'meeting-123',
  documents: [
    {
      url: 'https://example.com/presentation.pdf',
      filename: 'slides.pdf'
    }
  ]
});
console.log('Status:', result.returncode);

// Insert multiple documents with options
await client.insertDocument({
  meetingID: 'meeting-123',
  documents: [
    {
      url: 'https://example.com/doc1.pdf',
      filename: 'document1.pdf',
      downloadable: true,
      removable: false
    },
    {
      content: 'JVBERi0xLjQKJeLjz9MKMy...',  // Base64 encoded PDF
      filename: 'document2.pdf'
    }
  ]
});

Error Handling

The library provides custom error classes for better error handling:

import {
  BBBError,          // Base error class
  BBBAPIError,       // API returned error
  BBBNetworkError,   // Network request failed
  BBBParseError,     // XML parsing failed
  BBBConfigError     // Invalid configuration
} from 'bbb-api-js';

try {
  const meeting = await client.create({
    meetingID: 'test',
    name: 'Test Meeting'
  });
} catch (error) {
  if (error instanceof BBBAPIError) {
    console.error('API Error:', error.message);
    console.error('Message Key:', error.messageKey);
  } else if (error instanceof BBBNetworkError) {
    console.error('Network Error:', error.message);
  } else if (error instanceof BBBConfigError) {
    console.error('Configuration Error:', error.message);
  }
}

Complete Example

Here's a complete example showing a typical workflow:

import { BBBClient } from 'bbb-api-js';

async function runMeeting() {
  // Initialize client
  const client = new BBBClient({
    serverUrl: 'https://bbb.example.com/bigbluebutton/api',
    secret: 'your-shared-secret'
  });

  try {
    // Create a meeting
    const meeting = await client.create({
      meetingID: 'demo-meeting',
      name: 'Demo Meeting',
      attendeePW: 'attendee123',
      moderatorPW: 'moderator456',
      record: true,
      autoStartRecording: true,
      allowStartStopRecording: true,
      welcome: 'Welcome to the demo!',
      meta_description: 'This is a demo meeting'
    });

    console.log('Meeting created successfully!');
    console.log('Meeting ID:', meeting.meetingID);

    // Generate join URLs
    const moderatorUrl = client.join({
      fullName: 'Moderator',
      meetingID: meeting.meetingID,
      password: meeting.moderatorPW
    });

    const attendeeUrl = client.join({
      fullName: 'Attendee',
      meetingID: meeting.meetingID,
      password: meeting.attendeePW
    });

    console.log('Moderator URL:', moderatorUrl);
    console.log('Attendee URL:', attendeeUrl);

    // Wait a bit, then check meeting info
    await new Promise(resolve => setTimeout(resolve, 5000));

    const info = await client.getMeetingInfo(meeting.meetingID);
    console.log('Meeting is running:', info.running);
    console.log('Participant count:', info.participantCount);

    // Get recordings (if any exist)
    const recordings = await client.getRecordings({
      meetingID: meeting.meetingID
    });

    console.log('Recordings found:', recordings.length);

    // End the meeting
    await client.endMeeting(meeting.meetingID, meeting.moderatorPW);
    console.log('Meeting ended');

  } catch (error) {
    console.error('Error:', error);
  }
}

runMeeting();

TypeScript Support

This library is written in TypeScript and provides full type definitions. All parameters and return types are fully typed:

import type {
  BBBClientConfig,
  CreateMeetingParams,
  CreateMeetingResponse,
  JoinMeetingParams,
  MeetingInfo,
  Recording,
  Attendee
} from 'bbb-api-js';

// Your IDE will provide full autocomplete and type checking

Development

Build

npm run build

Run Tests

npm test

Run Tests with Coverage

npm run test:coverage

License

ISC

Links

• BigBlueButton Official Website
• BigBlueButton API Documentation

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.