Digital Samba

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

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").

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

SDK / Client Errors

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