digital-samba

name	digital-samba
description	Build video conferencing integrations using Digital Samba's API and SDK. Use when creating meeting rooms, embedding video calls, generating participant tokens, managing recordings, or integrating real-time collaboration features. Triggers include "Digital Samba", "video conferencing API", "embed video calls", "meeting room integration", "WebRTC iframe", "participant tokens".

Digital Samba Integration

Build video conferencing into your applications using Digital Samba's prebuilt infrastructure. No WebRTC/Janus/TURN setup required.

Two Integration Approaches

1. REST API - Server-side room/session/participant management
2. Embedded SDK - Client-side iframe control and event handling

Quick Start

1. Create a Room (Server-side)

curl -X POST https://api.digitalsamba.com/api/v1/rooms \
  -H "Authorization: Bearer {DEVELOPER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"friendly_url": "my-meeting", "privacy": "public"}'

2. Generate Access Token (Server-side)

const jwt = require('jsonwebtoken');

const token = jwt.sign({
  td: "team-uuid",      // Your team ID
  rd: "room-uuid",      // Room ID from step 1
  u: "John Doe",        // User display name
  role: "moderator"     // Optional: user role
}, DEVELOPER_KEY, { algorithm: 'HS256' });

3. Embed the Room (Client-side)

Option A: Plain iframe — simplest, no SDK needed:

<iframe
  id="video-frame"
  allow="camera; microphone; display-capture; autoplay;"
  src="https://yourteam.digitalsamba.com/my-meeting?token={jwt}"
  style="width: 100%; height: 100vh; border: none;"
  allowfullscreen="true">
</iframe>

Option B: SDK creates the iframe — lets you add event listeners before loading:

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

// SDK injects an iframe into this container element
const sambaFrame = DigitalSambaEmbedded.createControl({
  url: 'https://yourteam.digitalsamba.com/my-meeting?token={jwt}',
  root: document.getElementById('video-container') // Container div, not an iframe
});

// Set up events before the iframe loads
sambaFrame.on('userJoined', (e) => console.log(`${e.data.user.name} joined`));
sambaFrame.on('appError', (e) => console.error(`[${e.data.code}] ${e.data.message}`));
sambaFrame.on('mediaConnectionFailed', () => console.error('Could not reach the media server'));

sambaFrame.load(); // Now create and load the iframe

Option C: SDK wraps an existing iframe — control an iframe you already placed in HTML:

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

// Wrap the iframe from Option A to add SDK control
const sambaFrame = DigitalSambaEmbedded.createControl({
  frame: document.getElementById('video-frame') // Existing iframe element
});

sambaFrame.on('userJoined', (e) => console.log(`${e.data.user.name} joined`));

Important: The SDK iframe container must have explicit CSS dimensions (width + height). The iframe does not auto-size. See Iframe Sizing in patterns.md.

When to Use What

Need	Use
Create/delete rooms	REST API
User authentication	JWT tokens
Embed video UI	iframe + SDK
Start/stop recording	REST API or SDK
React to events	SDK events
Manage participants	REST API
Customize UI	Room settings API

Pre-Built Integration Patterns

The skill includes ready-to-use code patterns for common use cases. Ask your AI assistant for a pattern by describing your use case (e.g., "build a virtual classroom", "add video to my booking system", "set up a webinar page").

Pattern	Best For	Key Features
Simple Public Room	Quick demos, open meetings	Minimal setup, public access, no auth required
Authenticated Users	SaaS integrations, known users	JWT tokens, role-based access, error handling
SDK-Controlled Room	Custom UIs, programmatic control	Event handling, mute/unmute, custom buttons
Scheduled Meetings	Calendar integrations, booking systems	Time constraints, invite tokens, email invites
Webinar Mode	One-to-many broadcasts	Presenter/attendee roles, Q&A, raise hand
Recording & Playback	Content archiving, compliance	Start/stop recording, download, playback
Online Learning Platform	LMS, virtual classrooms, tutoring	Instructor/student roles, attendance tracking, lesson recordings, per-course rooms
Playwright E2E Testing	Automated testing, CI/CD	Iframe testing, SDK events, demo recordings

Each pattern includes complete server-side and client-side code. See patterns.md for full implementations.

Reference Documentation

For detailed information, see these reference files:

• api-reference.md - Complete REST API endpoints
• sdk-reference.md - SDK methods, events, properties
• patterns.md - Pre-built integration patterns with full code examples
• jwt-tokens.md - Authentication deep-dive

Key Concepts

Room Types

• Public: Anyone with URL can join (enters name on join screen)
• Private: Requires JWT token to join

Roles & Permissions

Assign roles via JWT role field. Common roles:

• moderator - Full control (mute others, recording, etc.)
• speaker - Can present and speak
• attendee - View/listen only (configurable)

Authentication Flow

1. Developer key → Server-side API calls only (find it in Dashboard → Team Settings → Developer)
2. JWT tokens → Client-side room access (signed with the developer key using HS256)
3. Never expose developer key to browsers — use it only on your server

Common Errors

API Errors

Code	Meaning	Solution
401	Invalid/missing key	Check Authorization header
403	Insufficient permissions	Verify role/permissions
404	Room not found	Check room UUID/URL
422	Validation error	Check request body; see errors field for per-field details
429	Rate limited	Back off and retry with exponential delay

SDK / Client Errors

Issue	Cause	Solution
SDK won't load	Not a secure context	Serve over HTTPS (localhost exempt) — check window.isSecureContext
appError event	Runtime error from the embedded app	Check e.data.code and e.data.message for details
mediaConnectionFailed event	Media connection to the server could not be established	Check network/firewall; verify the room URL and token
mediaPermissionsFailed event	Browser denied camera/mic access	Prompt the user to grant permissions and reload
Nothing happens, no events at all	Bad room URL or config, silently logged to console	Call sambaFrame.load({ reportErrors: true }) to make init errors throw
iframe blank / no video	Missing allow attribute	Add allow="camera; microphone; display-capture; autoplay" to iframe

For detailed troubleshooting steps, diagnostic code examples, and API error breakdowns, see the Troubleshooting & Diagnostics section in patterns.md.

Check for Updates

To check if your installed skill is up to date:

1. Local version: cat .claude/skills/digital-samba/VERSION
2. Latest version: curl -s https://api.github.com/repos/digitalsamba/digital-samba-skill/releases/latest | grep '"tag_name"'

To update (submodule install):

git submodule update --remote .claude/skills/digital-samba

To update (manual install): Re-clone and copy skill files from https://github.com/digitalsamba/digital-samba-skill

Resources

• API Reference: https://developer.digitalsamba.com/rest-api/
• SDK NPM: https://www.npmjs.com/package/@digitalsamba/embedded-sdk
• Dashboard: https://dashboard.digitalsamba.com
• Skill Releases: https://github.com/digitalsamba/digital-samba-skill/releases