Digital Samba Embedded SDK Reference

Package: @digitalsamba/embedded-sdk Version: 0.0.55 License: BSD-2-Clause

Installation

npm install @digitalsamba/embedded-sdk

Or via CDN:

<script src="https://unpkg.com/@digitalsamba/embedded-sdk"></script>

Production recommendation: Bundle the SDK into your application rather than fetching from npm/CDN at runtime. npm and CDN outages can break your app's availability. Use your bundler (webpack, vite, esbuild) to include it in your production build.

Security Requirement

The SDK requires a secure context (HTTPS). Local development accepts:

http://localhost
http://127.0.0.1

Initialization

Method 1: Direct Constructor

import DigitalSambaEmbedded from '@digitalsamba/embedded-sdk';

const sambaFrame = new DigitalSambaEmbedded({
  url: 'https://team.digitalsamba.com/room?token=xxx',
  root: document.getElementById('video-container')
});

Method 2: Deferred Loading (Recommended)

const sambaFrame = DigitalSambaEmbedded.createControl({
  url: 'https://team.digitalsamba.com/room?token=xxx',
  root: document.getElementById('video-container')
});

// Configure before loading
sambaFrame.on('userJoined', handleJoin);

// Load when ready
sambaFrame.load();

Method 3: Wrap Existing iframe

const sambaFrame = DigitalSambaEmbedded.createControl({
  frame: document.getElementById('existing-iframe')
});

InitOptions

Option	Type	Description
`url`	string	Full iframe URL with token
`root`	HTMLElement	Container element for iframe
`frame`	HTMLIFrameElement	Existing iframe to control
`team`	string	Team identifier (alternative to url)
`room`	string	Room identifier (alternative to url)
`token`	string	JWT token (alternative to url)
`roomSettings`	object	Room settings overrides (see below)

roomSettings options:

Option	Type	Description
`baseDomain`	string	Override base domain
`publicRoomUrl`	string	Override public room URL used for invitation links
`mobileScreenshare`	boolean	Enable mobile screenshare
`videoEnabled`	boolean	Start with camera on/off
`audioEnabled`	boolean	Start with mic on/off
`username`	string	Override display name
`initials`	string	Override avatar initials
`layoutMode`	`'auto' \| 'tiled'`	Starting layout mode
`showToolbar`	boolean	Show/hide toolbar
`showTopbar`	boolean	Show/hide topbar
`joinScreenEnabled`	boolean	Show/hide the join screen (name/device entry) before entering the room
`showCaptions`	boolean	Show captions initially
`virtualBackground`	object	Pre-configure virtual background
`virtualBackgrounds`	array	Custom background options
`replaceVirtualBackgrounds`	boolean	Replace default backgrounds
`appLanguage`	string	UI language
`muteFrame`	boolean	Start with frame muted
`mediaDevices`	object	Pre-select audio/video devices
`requireRemoveUserConfirmation`	boolean	Confirm before removing users

Properties

sambaFrame.localUser

Current user information.

const user = sambaFrame.localUser;
// {
//   id: "08c82f56-c670-4d36-bfe3-87a8cd0f7f29",
//   name: "John",
//   avatarColor: "#90c695",
//   role: "moderator",
//   kind: "local"
// }

sambaFrame.features

Available room features (boolean flags).

console.log(sambaFrame.features.chat);        // true
console.log(sambaFrame.features.recordings);  // true
console.log(sambaFrame.features.screenshare); // true

Available features:

chat
endSession
fullScreen
languageSelection
minimizeOwnTile
participantsList
pin
screenshare
recordings
virtualBackgrounds
raiseHand
invite
qa
contentLibrary
whiteboard
captions

sambaFrame.roomState

Current room state.

interface RoomState {
  appLanguage: string;
  audioOnly: boolean;
  frameMuted: boolean;
  media: {
    videoEnabled: boolean;
    audioEnabled: boolean;
    activeDevices: {
      videoinput: string;
      audioinput: string;
      audiooutput: string;
    }
  };
  layout: {
    mode: 'auto' | 'tiled';
    showToolbar: boolean;
    showTopbar: boolean;
    toolbarPosition: 'left' | 'right' | 'bottom';
    localTileMinimized: boolean;
    contentMode?: 'maximize' | 'pin';
    content?: { userId: string; type: string };
  };
  captionsState: {
    showCaptions: boolean;
    spokenLanguage: string;
    fontSize: 'small' | 'medium' | 'large';
  };
  virtualBackground: {
    enabled: boolean;
    enforced?: boolean;
    type?: 'blur' | 'image' | 'imageUrl';
    name?: string;
    value?: string;
  };
}

sambaFrame.permissionManager

Check user permissions.

// Check single permission
const canBroadcast = sambaFrame.permissionManager.hasPermissions('broadcast');

// Check multiple permissions
const canModerate = sambaFrame.permissionManager.hasPermissions([
  'remoteMuting',
  'removeParticipant'
]);

// Check for specific role
const moderatorCanRecord = sambaFrame.permissionManager.hasPermissions(
  'recording',
  { targetRole: 'moderator' }
);

Permission Types:

broadcast - Send audio/video
manageBroadcast - Control others' broadcast
endSession - End meeting for all
startSession - Start meeting
removeParticipant - Kick users
screenshare - Share screen
manageScreenshare - Control others' screenshare
recording - Start/stop recording
generalChat - Send chat messages
remoteMuting - Mute other users
askRemoteUnmute - Request unmute
raiseHand - Raise hand
manageRoles - Change user roles
inviteParticipant - Invite users to room
seeParticipantsPanel - View participants list
controlRoomEntry - Control room entry (lobby)
editWhiteboard - Edit whiteboard content

Events

Subscribing to Events

// Subscribe to recurring events
sambaFrame.on('userJoined', (event) => {
  console.log(`${event.data.name} joined`);
});

// One-time subscription
sambaFrame.once('frameLoaded', () => {
  console.log('Frame ready');
});

// Unsubscribe
sambaFrame.off('userJoined', handlerFunction);

// Debug: log all events
sambaFrame.on('*', (event) => {
  console.log(event.type, event.data);
});

Event Reference

Connection Events

Event	Payload	Description
`frameLoaded`	-	iframe loaded and ready
`userJoined`	`{ id, name, role }`	Local user joined room
`userLeft`	`{ id, name }`	User left room
`usersUpdated`	`User[]`	Participant list changed
`sessionEnded`	-	Meeting ended

Media Events

Event	Payload	Description
`audioEnabled`	-	Local mic turned on
`audioDisabled`	-	Local mic turned off
`videoEnabled`	-	Local camera turned on
`videoDisabled`	-	Local camera turned off
`screenshareStarted`	`{ userId }`	Screen sharing began
`screenshareStopped`	`{ userId }`	Screen sharing ended
`activeSpeakerChanged`	`{ userId }`	Active speaker changed
`speakerStoppedTalking`	`{ userId }`	Speaker went silent
`mediaDeviceChanged`	`{ type, deviceId }`	Device selection changed

Recording Events

Event	Payload	Description
`recordingStarted`	-	Recording began
`recordingStopped`	-	Recording ended
`recordingFailed`	`{ error }`	Recording error

UI Events

Event	Payload	Description
`layoutModeChanged`	`{ mode }`	Layout changed
`appLanguageChanged`	`{ language }`	UI language changed
`roomStateUpdated`	`RoomState`	Any room state changed
`featureSetUpdated`	`FeatureSet`	Available features changed

Layout Events

Event	Payload	Description
`localTileMaximized`	-	Local tile was maximized
`localTileMinimized`	-	Local tile was minimized
`userMaximized`	`{ userId, type, mode }`	User tile maximized/pinned

Caption Events

Event	Payload	Description
`captionsEnabled`	-	Captions turned on
`captionsDisabled`	-	Captions turned off
`captionsFontSizeChanged`	`{ size }`	Caption size changed
`captionsSpokenLanguageChanged`	`{ language }`	Spoken language changed

Interaction Events

Event	Payload	Description
`handRaised`	`{ userId }`	User raised hand
`handLowered`	`{ userId }`	User lowered hand
`chatMessageReceived`	`{ message, userId }`	Chat message received
`roleChanged`	`{ userId, role }`	User role changed
`permissionsChanged`	`{ permissions }`	Permissions updated

Virtual Background Events

Event	Payload	Description
`virtualBackgroundChanged`	`{ type, value }`	Background changed
`virtualBackgroundDisabled`	-	Background disabled

Error Events

Event	Payload	Description
`appError`	`{ code, message }`	Application error
`mediaConnectionFailed`	-	Media connection to the SFU could not be established (e.g. network/firewall issue)
`mediaPermissionsFailed`	-	Browser denied media device access

Method Quick Reference

Every SDK method at a glance. Use exact names below — see detailed docs in sections that follow.

Category	Method	Description
Lifecycle	`load()`	Load the iframe (deferred mode)
Lifecycle	`leaveSession()`	Leave the session
Lifecycle	`endSession(showConfirm?)`	End session for all participants
Video	`enableVideo()`	Turn camera on
Video	`disableVideo()`	Turn camera off
Video	`toggleVideo(force?)`	Toggle or force camera state
Audio	`enableAudio()`	Turn mic on
Audio	`disableAudio()`	Turn mic off
Audio	`toggleAudio(force?)`	Toggle or force mic state
Screenshare	`startScreenshare()`	Start screen sharing
Screenshare	`stopScreenshare()`	Stop screen sharing
Recording	`startRecording()`	Start recording
Recording	`stopRecording()`	Stop recording
Restreaming	`startRestreaming()`	Start RTMP restreaming
Restreaming	`stopRestreaming()`	Stop RTMP restreaming
Users	`listUsers()`	Get all participants
Users	`getUser(userId)`	Get specific participant
Users	`removeUser(userId)`	Remove participant from room
Users	`changeRole(userId, role)`	Change participant's role
Moderation	`requestMute(userId)`	Request user mute
Moderation	`requestUnmute(userId)`	Request user unmute
Moderation	`requestToggleAudio(userId, force?)`	Toggle user's audio
Broadcast	`allowBroadcast(userId\|options)`	Grant broadcast permission
Broadcast	`disallowBroadcast(userId)`	Revoke broadcast permission
Broadcast	`allowScreenshare(userId)`	Grant screenshare permission
Broadcast	`disallowScreenshare(userId)`	Revoke screenshare permission
Hand Raise	`raiseHand()`	Raise own hand
Hand Raise	`lowerHand(userId?)`	Lower hand (own or other's)
Toolbar	`showToolbar()`	Show toolbar
Toolbar	`hideToolbar()`	Hide toolbar
Toolbar	`toggleToolbar()`	Toggle toolbar visibility
Toolbar	`changeToolbarPosition(pos)`	Move toolbar: `'left'\|'right'\|'bottom'`
Topbar	`showTopbar()`	Show topbar
Topbar	`hideTopbar()`	Hide topbar
Topbar	`toggleTopbar()`	Toggle topbar visibility
Layout	`changeLayoutMode(mode)`	Set layout: `'auto'\|'tiled'`
Tiles	`pinUser(userId, type?)`	Pin user's video tile
Tiles	`unpinUser()`	Unpin current pinned tile
Tiles	`maximizeUser(userId, type?)`	Maximize user's video tile
Tiles	`minimizeUser()`	Minimize maximized tile
Tiles	`minimizeLocalTile()`	Minimize own tile
Tiles	`maximizeLocalTile()`	Maximize own tile
Tiles	`minimizeContent()`	Minimize pinned/maximized content
Frame Audio	`muteFrame()`	Mute all iframe audio output
Frame Audio	`unmuteFrame()`	Unmute iframe audio output
Frame Audio	`toggleMuteFrame()`	Toggle iframe audio mute
Captions	`showCaptions()`	Show captions
Captions	`hideCaptions()`	Hide captions
Captions	`toggleCaptions()`	Toggle captions
Captions	`configureCaptions(options)`	Set font size, language, apply to all
Virtual BG	`enableVirtualBackground(options)`	Enable blur, image, or imageUrl background
Virtual BG	`disableVirtualBackground()`	Disable virtual background
Virtual BG	`configureVirtualBackground(options)`	Configure without enabling
Whiteboard	`createWhiteboard(options)`	Create new whiteboard
Whiteboard	`openWhiteboard(id)`	Open whiteboard
Whiteboard	`closeWhiteboard(id)`	Close whiteboard
Whiteboard	`toggleWhiteboard()`	Toggle whiteboard
Whiteboard	`addImageToWhiteboard(options)`	Add image via URL or base64
Library	`openLibraryFile(fileId)`	Open library file
Library	`closeLibraryFile(fileId)`	Close library file
Library	`toggleLibraryFile(fileId)`	Toggle library file
Features	`featureEnabled(name)`	Check if feature is enabled
Custom Tiles	`addCustomTile(options)`	Add custom HTML tile
Custom Tiles	`removeCustomTile(name)`	Remove custom tile
Custom Tiles	`sendMessageToCustomTile(options)`	Send data to custom tile
Tile Actions	`addTileAction(id, props, callback)`	Add custom tile menu action
Tile Actions	`removeTileAction(id)`	Remove custom tile action
UI Callbacks	`addUICallback(event, callback)`	Override UI interaction
UI Callbacks	`removeUICallback(event, callback)`	Remove UI override
Frame Events	`addFrameEventListener(event, target, handler)`	Listen to iframe JS events
Frame Events	`removeFrameEventListener(event, target, handler)`	Remove iframe listener
Branding	`changeBrandingOptions(options)`	Change theme/colors at runtime
Events	`on(event, handler)`	Subscribe to event
Events	`once(event, handler)`	One-time event subscription
Events	`off(event, handler)`	Unsubscribe from event

Methods (Detailed)

Media Control

// Video
sambaFrame.enableVideo();
sambaFrame.disableVideo();
sambaFrame.toggleVideo();        // Toggle current state
sambaFrame.toggleVideo(true);    // Force enable

// Audio
sambaFrame.enableAudio();
sambaFrame.disableAudio();
sambaFrame.toggleAudio();
sambaFrame.toggleAudio(false);   // Force disable

// Screen sharing
sambaFrame.startScreenshare();
sambaFrame.stopScreenshare();

// Recording
sambaFrame.startRecording();
sambaFrame.stopRecording();

// Restreaming (RTMP)
sambaFrame.startRestreaming();
sambaFrame.stopRestreaming();

User Management

// List all users
const users = sambaFrame.listUsers();

// Get specific user
const user = sambaFrame.getUser('user-id');

// Remove user from room
sambaFrame.removeUser('user-id');

// Change user's role
sambaFrame.changeRole('user-id', 'speaker');

// Mute requests
sambaFrame.requestMute('user-id');
sambaFrame.requestUnmute('user-id');
sambaFrame.requestToggleAudio('user-id');
sambaFrame.requestToggleAudio('user-id', true); // Request mute

Broadcasting Control

// Allow user to broadcast (moderator action)
sambaFrame.allowBroadcast('user-id');
sambaFrame.allowBroadcast({ userId: 'user-id', audio: true, video: false });

// Revoke broadcast permission
sambaFrame.disallowBroadcast('user-id');

// Screenshare permissions
sambaFrame.allowScreenshare('user-id');
sambaFrame.disallowScreenshare('user-id');

Hand Raising

// Raise own hand
sambaFrame.raiseHand();

// Lower hand (own or others if moderator)
sambaFrame.lowerHand();
sambaFrame.lowerHand('user-id');

UI Control

// Toolbar
sambaFrame.showToolbar();
sambaFrame.hideToolbar();
sambaFrame.toggleToolbar();
sambaFrame.changeToolbarPosition('left'); // 'left' | 'right' | 'bottom'

// Topbar
sambaFrame.showTopbar();
sambaFrame.hideTopbar();
sambaFrame.toggleTopbar();

// Layout
sambaFrame.changeLayoutMode('tiled'); // 'auto' | 'tiled'

Tile Management

// Pin user's video
sambaFrame.pinUser('user-id');
sambaFrame.pinUser('user-id', 'screenshare'); // Pin specific tile type
sambaFrame.unpinUser();

// Maximize user's video
sambaFrame.maximizeUser('user-id');
sambaFrame.maximizeUser('user-id', 'screenshare');
sambaFrame.minimizeUser();

// Local tile
sambaFrame.minimizeLocalTile();
sambaFrame.maximizeLocalTile();

// Minimize pinned/maximized content
sambaFrame.minimizeContent();

Frame Audio

// Mute all audio output from iframe
sambaFrame.muteFrame();
sambaFrame.unmuteFrame();
sambaFrame.toggleMuteFrame();

Captions

sambaFrame.showCaptions();
sambaFrame.hideCaptions();
sambaFrame.toggleCaptions();

sambaFrame.configureCaptions({
  fontSize: 'large',            // 'small' | 'medium' | 'large'
  spokenLanguage: 'en-US',
  applySpokenLanguageToAll: true // Apply spoken language to all participants (moderator only)
});

Virtual Background

// Enable blur
sambaFrame.enableVirtualBackground({ type: 'blur' });

// Enable image
sambaFrame.enableVirtualBackground({
  type: 'image',
  value: 'background-name'  // From configured backgrounds
});

// Enable custom image URL
sambaFrame.enableVirtualBackground({
  type: 'imageUrl',
  value: 'https://example.com/background.jpg'
});

// Disable
sambaFrame.disableVirtualBackground();

// Configure (set options without enabling)
sambaFrame.configureVirtualBackground({ type: 'blur' });

Whiteboard

// Create new whiteboard
sambaFrame.createWhiteboard({ personal: false, folderId: 'folder-id' });

// Open/close whiteboard
sambaFrame.openWhiteboard('whiteboard-id');
sambaFrame.closeWhiteboard('whiteboard-id');
sambaFrame.toggleWhiteboard();

// Add image to whiteboard (URL - requires CORS on external server)
sambaFrame.addImageToWhiteboard({
  url: 'https://example.com/diagram.png',
  position: { x: 100, y: 50 }  // Optional, auto-centers if omitted
});

// Add image via base64
sambaFrame.addImageToWhiteboard({
  base64: 'data:image/png;base64,iVBORw0KGgo...'
});

Library Files

// Open file from library
sambaFrame.openLibraryFile('file-id');
sambaFrame.closeLibraryFile('file-id');
sambaFrame.toggleLibraryFile('file-id');

Session Control

// Leave session (current user)
sambaFrame.leaveSession();

// End session for everyone (requires permission)
sambaFrame.endSession();
sambaFrame.endSession(true); // Show confirmation dialog

Feature Check

// Check if feature is enabled
if (sambaFrame.featureEnabled('recordings')) {
  showRecordButton();
}

Advanced Features

Custom Tile Actions

Add custom actions to the 3-dots menu on video tiles.

// Add a custom action to remote user tiles
sambaFrame.addTileAction(
  'sendEmail',                              // Action identifier
  { label: 'Send Email', scope: 'remote' }, // Properties
  () => console.log('Send email clicked')   // Callback
);

// Remove the action
sambaFrame.removeTileAction('sendEmail');

Scope values:

'all' - All tiles
'remote' - Other users' tiles
'local' - Current user's tile
'screenshare-local' - Local screen share
'screenshare-remote' - Remote screen share

Custom Tiles

Add custom HTML panels to the video call UI.

// Add a custom tile (must be called after userJoined)
sambaFrame.addCustomTile({
  name: 'poll-panel',           // Tile identifier and title
  html: '<div>Poll content</div>', // HTML content
  position: 'last'              // 'first' or 'last' in tile list
});

// Remove a custom tile
sambaFrame.removeCustomTile('poll-panel');

// Send data to the custom tile's iframe
sambaFrame.sendMessageToCustomTile({
  name: 'poll-panel',           // Must match addCustomTile name
  event: 'updateResults',       // Custom event name (optional)
  origin: '*',                  // postMessage origin (optional)
  data: { results: [1, 2, 3] }  // Payload (optional)
});

Receiving messages in the custom tile:

window.addEventListener('message', (event) => {
  console.log(event.data); // { event: 'updateResults', data: { results: [1, 2, 3] } }
});

UI Callbacks

Override UI interactions with custom logic. The default action is suppressed.

// Override leave session with confirmation
const leaveCallback = () => {
  if (confirm('Are you sure you want to leave?')) {
    sambaFrame.leaveSession();
  }
};

sambaFrame.addUICallback('leaveSession', leaveCallback);

// Remove the override
sambaFrame.removeUICallback('leaveSession', leaveCallback);

Supported events: 'leaveSession'

Frame Event Listeners

Listen to JavaScript events inside the iframe (e.g., for custom key combinations).

// Listen for keyup on window
const keyHandler = (payload) => console.log('keyup', payload);
sambaFrame.addFrameEventListener('keyup', 'window', keyHandler);

// Listen for clicks on document
const clickHandler = (payload) => console.log('click', payload);
sambaFrame.addFrameEventListener('click', 'document', clickHandler);

// Remove listener
sambaFrame.removeFrameEventListener('keyup', 'window', keyHandler);

Targets: 'window' or 'document'

Runtime Branding

Change room appearance without reloading.

// Switch to dark theme
sambaFrame.changeBrandingOptions({ paletteMode: 'dark' });

// Custom colors
sambaFrame.changeBrandingOptions({
  primaryColor: '#0066FF',       // Accent color
  toolbarColor: '#1a1a1a',       // Toolbar background
  roomBackgroundColor: '#000000' // Room background
});

Options:

paletteMode - 'dark' or 'light'
primaryColor - Hex color for accents
toolbarColor - Hex color for toolbar
roomBackgroundColor - Hex color for background

TypeScript Support

import DigitalSambaEmbedded, {
  InitOptions,
  User,
  RoomState,
  FeatureSet,
  PermissionTypes
} from '@digitalsamba/embedded-sdk';

const sambaFrame: DigitalSambaEmbedded = DigitalSambaEmbedded.createControl({
  url: roomUrl,
  root: container
});

sambaFrame.on('userJoined', (event: { data: User }) => {
  console.log(event.data.name);
});

Important: Wait for userJoined

Most methods have no effect before the user joins. Always wait:

sambaFrame.once('userJoined', () => {
  // Now safe to call methods
  sambaFrame.disableAudio();
});
sambaFrame.load();

FilesExpand file tree

sdk-reference.md

Latest commit

History