SuperAPI AI Directory

digital-samba

Coding & development

View repository

Updated 11-01 09:35

About this skill

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:

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