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.name} joined`));
sambaFrame.on('connectionFailure', (e) => console.error('Failed:', e.data));

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