Telephony Integration Guide

Digital Samba supports SIP/PSTN telephony integration allowing phone callers to join rooms. This guide explains how to build a custom telephony integration using any SIP/Voice API provider.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Phone Callers  │────▶│  Your Voice     │────▶│  Digital Samba  │
│  (PSTN)         │     │  API Provider   │     │  Room           │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
                              │ SIP Connection
                              ▼
                        ┌─────────────────┐
                        │  Your Middleware│
                        │  Application    │
                        └─────────────────┘

The integration consists of:

1. Voice API Provider - Handles phone calls, IVR prompts, and PSTN conferencing (e.g., Twilio, Sinch, Vonage, Plivo)

2. SIP Trunk - Connects your Voice API to Digital Samba

3. Middleware Application - Routes calls, manages PINs, and synchronises state between your Voice API and Digital Samba

4. Digital Samba Room - Video conferencing room with telephony enabled

Prerequisites

Before starting your integration:

1. Digital Samba Account with API access

2. Voice API Provider Account with:

   • A phone number for incoming calls

   • Voice/conferencing API access

   • SIP trunking capability

3. SIP Trunk Configuration - Contact Digital Samba support to configure IP whitelisting and authentication for your SIP trunk

Important: Before proceeding with implementation, contact Digital Samba support to set up your SIP trunk. Provide your SIP provider details and we will guide you through IP whitelisting and authentication configuration.

Architecture Overview

System Components

┌────────────────────────────────────────────────────────────────────────┐
│                        Your Integration                                │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌──────────────┐      ┌──────────────────┐      ┌──────────────────┐  │
│  │  Voice API   │      │   Middleware     │      │   Digital Samba  │  │
│  │  Provider    │◀────▶│   Application    │◀────▶│   API            │  │
│  │              │      │                  │      │                  │  │
│  │ • Phone #    │      │ • Call routing   │      │ • Room creation  │  │
│  │ • IVR        │      │ • PIN validation │      │ • Phone user API │  │
│  │ • Conference │      │ • SIP control    │      │ • Webhooks       │  │
│  │ • SIP trunk  │      │ • State sync     │      │ • Mute control   │  │
│  └──────────────┘      └──────────────────┘      └──────────────────┘  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Call Flow Sequence

Phone User              Voice Provider          Your App            Digital Samba
    │                        │                     │                     │
    │ 1. Dial phone number   │                     │                     │
    │───────────────────────▶│                     │                     │
    │                        │ 2. Webhook: ICE     │                     │
    │                        │────────────────────▶│                     │
    │                        │                     │                     │
    │ 3. IVR: "Enter PIN"    │                     │                     │
    │◀───────────────────────│◀────────────────────│                     │
    │                        │                     │                     │
    │ 4. Enter PIN (e.g. 123)│                     │                     │
    │───────────────────────▶│ 5. DTMF callback    │                     │
    │                        │────────────────────▶│                     │
    │                        │                     │ 6. Validate PIN     │
    │                        │                     │───────┐             │
    │                        │                     │       │             │
    │                        │                     │◀──────┘             │
    │                        │ 7. Connect to conf  │                     │
    │                        │◀────────────────────│                     │
    │                        │                     │                     │
    │ 8. Joined conference   │                     │ 9. Phone user joined│
    │◀───────────────────────│                     │────────────────────▶│
    │                        │                     │                     │
    │ 10. Hear room audio    │                     │                     │
    │◀═══════════════════════│═════════════════════│═════════════════════│
    │                        │ (via SIP bridge)    │                     │

Step 1: Configure Digital Samba Room

Create a Telephony-Enabled Room

When creating a room via the API, include the telephony configuration:

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Telephony Room",
    "friendly_url": "telephony-room",
    "telephony_enabled": true,
    "telephony_phone_number": "[phone]",
    "telephony_pin_dtmf": "WWW123#"
  }'

Telephony Room Properties

Property	Type	Description
telephony_enabled	boolean	Enable telephony for this room
telephony_phone_number	string	The phone number for SIP to dial into your Voice API conference
telephony_pin_dtmf	string	DTMF sequence for SIP to enter when connecting to the conference

DTMF Sequence Format

The telephony_pin_dtmf field uses special characters:

Character	Meaning
W	Wait 1 second (for IVR prompts)
w	Wait 0.5 seconds
0-9	Dial digit
*	Dial asterisk
#	Dial pound/hash (often used as terminator)

Example: WWW123# means:

• Wait 3 seconds for IVR prompt

• Dial 123

• Press # to confirm

Step 2: Build Your Middleware Application

Your middleware application handles communication between your Voice API provider and Digital Samba.

Core Responsibilities

1. Handle incoming calls from your Voice API provider

2. Play IVR prompts and collect PIN input

3. Route callers to the correct conference based on PIN

4. Manage SIP connection to Digital Samba room

5. Synchronise phone user state with Digital Samba API

6. Handle webhooks from both Voice API and Digital Samba

Conference and PIN Management

Your application must maintain a mapping between:

• Digital Samba room IDs

• Voice API conference IDs

• PINs for phone callers

• PINs for SIP bridge connections

Important: Voice API providers do not have inherent knowledge of conferences until you create them. You must build your own database and logic to:

• Generate and assign PINs

• Map PINs to conferences

• Route callers based on PIN input

Example PIN Structure

// Example conference mapping
const conferenceMapping = {
  conferences: {
    "conf_123": {
      digitalSambaRoomId: "a74d5723-6b98-45e3-8135-149e57fe9072",
      voiceApiConferenceId: "your-provider-conf-id",
      callerPins: ["1234", "5678", "9012"],  // PINs for phone users
      sipPin: "11",  // PIN for SIP bridge connection
      sipDtmfSequence: "WWW11#"
    }
  }
};

Identifying the SIP Connection

When the SIP bridge connects to your Voice API conference, you must identify it distinctly from regular phone callers. Common approaches:

1. Reserved PIN - Use a specific PIN only for SIP connections

2. Display Name - Check for a specific display name (e.g., starts with "SIP")

3. Origination Type - Check call metadata for SIP origin

4. Domain - Check if domain equals "SIP"

Critical: Do NOT notify Digital Samba when the SIP bridge joins. The SIP connection is not a "real" phone user—it's the audio bridge between your Voice API conference and the Digital Samba room.

Step 3: Digital Samba Phone User API

Notify When Phone Users Join

When a phone caller successfully joins your Voice API conference (after PIN validation and only after SIP is connected), notify Digital Samba:

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/rooms/{room_id}/phone-participants-joined \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [
      {
        "callId": "unique-call-identifier",
        "name": "Phone User 1",
        "callerNumber": "[phone]",
        "externalId": "your-internal-user-id"
      }
    ]
  }'

Request Parameters

Parameter	Type	Required	Description
callId	string	Yes	Unique identifier for this phone call (from your Voice API)
name	string	No	Display name for the phone user
callerNumber	string	No	Phone number of the caller
externalId	string	No	Your internal user identifier

Note: The externalId parameter is reserved for future functionality. It may be used to link phone participants with web participants who share the same external ID.

Notify When Phone Users Leave

When a phone caller disconnects:

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/rooms/{room_id}/phone-participants-left \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --header 'Content-Type: application/json' \
  --data '{
    "callIds": ["unique-call-identifier"]
  }'

Raise Hand for Phone User

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/rooms/{room_id}/phone-participants/{callId}/raise-hand \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY

Lower Hand for Phone User

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/rooms/{room_id}/phone-participants/{callId}/lower-hand \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY

Step 4: Configure Digital Samba Webhooks

Set up webhooks to receive events from Digital Samba rooms. This enables you to synchronise actions (like mute/unmute) with your Voice API.

Create a Webhook

curl --request POST \
  --url https://api.digitalsamba.com/api/v1/webhooks \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "https://your-app.com/webhooks/digitalsamba",
    "name": "Telephony Integration Webhook",
    "events": [
      "participant_joined",
      "participant_left",
      "session_started",
      "session_ended"
    ],
    "authorization_header": "your-webhook-secret"
  }'

Relevant Webhook Events

Event	Description
participant_joined	Triggered when any participant (web or phone) joins
participant_left	Triggered when any participant leaves
session_started	Triggered when a room session begins
session_ended	Triggered when a room session ends

Webhook Security

Always validate that webhook requests are legitimately from Digital Samba by checking the Authorization header matches your configured secret.

// Example webhook validation
app.post('/webhooks/digitalsamba', (req, res) => {
  const authHeader = req.headers['authorization'];
  
  if (authHeader !== 'your-webhook-secret') {
    return res.status(401).send('Unauthorized');
  }
  
  // Process webhook
  const event = req.body;
  handleDigitalSambaEvent(event);
  
  res.status(200).send('OK');
});

Step 5: Initiate SIP Connection

When a moderator in the Digital Samba room clicks "Connect Telephony" (requires the "Manage phone users" permission), Digital Samba initiates a SIP call to your Voice API.

What Happens

1. Digital Samba's SIP server calls the configured telephony_phone_number

2. Your Voice API answers and plays IVR

3. SIP sends the telephony_pin_dtmf sequence

4. Your application routes SIP to the correct conference

5. Room audio is now bridged to the PSTN conference

Important Timing

• Moderators should connect telephony early in the session if phone users are expected

• Phone users who call before SIP is connected will be in the Voice API conference but won't hear room audio

• Only notify Digital Samba of phone users after SIP has connected

Step 6: Managing Phone Users in Room

Once connected, phone users appear in the Digital Samba participant list. Moderators can:

• See phone users in the participants panel

• Mute/unmute phone users via the menu

• Remove phone users from the room

Handling Mute/Unmute

When a moderator mutes a phone user in Digital Samba, you'll receive a webhook. Your middleware should then call your Voice API to mute that participant in the PSTN conference.

// Example mute handler
function handleMuteEvent(event) {
  if (event.type === 'phone_participant_muted') {
    const callId = event.data.callId;
    
    // Call your Voice API to mute this participant
    voiceApi.muteParticipant(callId);
  }
}

Integration Checklist

Before Development

• [ ] Contact Digital Samba support to configure SIP trunk

• [ ] Set up Voice API provider account with phone number

• [ ] Understand your Voice API's webhook/callback structure

• [ ] Plan your PIN/conference management strategy

Development

• [ ] Create rooms with telephony enabled via API

• [ ] Build middleware to handle Voice API callbacks

• [ ] Implement IVR flow for PIN collection

• [ ] Build PIN validation and conference routing

• [ ] Integrate Digital Samba Phone User API

• [ ] Set up webhook handlers for Digital Samba events

• [ ] Implement mute/unmute synchronisation

Testing

• [ ] Test phone dial-in flow end-to-end

• [ ] Verify SIP connection with correct PIN/DTMF

• [ ] Confirm phone users appear in Digital Samba room

• [ ] Test mute/unmute from room to phone

• [ ] Test phone user disconnect handling

• [ ] Verify audio quality and latency

API Reference

Phone Participants Endpoints

Method	Endpoint	Description
POST	/api/v1/rooms/{room}/phone-participants-joined	Notify phone users joined
POST	/api/v1/rooms/{room}/phone-participants-left	Notify phone users left
POST	/api/v1/rooms/{room}/phone-participants/{callId}/raise-hand	Raise hand for phone user
POST	/api/v1/rooms/{room}/phone-participants/{callId}/lower-hand	Lower hand for phone user

Room Creation with Telephony

Include these properties when creating or updating rooms:

{
  "telephony_enabled": true,
  "telephony_phone_number": "[phone]",
  "telephony_pin_dtmf": "WWW123#"
}

Troubleshooting

SIP Connection Issues

Issue	Possible Cause	Solution
SIP cannot connect	IP not whitelisted	Contact DS support to verify IP whitelist
No audio after SIP connects	Wrong DTMF sequence	Verify PIN and timing in telephony_pin_dtmf
SIP connects but no phone users	Phone users notified before SIP	Only call phone-participants-joined after SIP connects

Common Mistakes

1. Notifying Digital Samba when SIP joins - The SIP bridge is not a phone user; do not send phone-participants-joined for it

2. Phone users notified before SIP connects - Phone users won't hear room audio until SIP is bridged; wait for SIP before notifying DS

3. Missing DTMF terminator - Many IVR systems require # to confirm PIN entry

4. Insufficient wait time - If IVR prompts are long, increase W characters in DTMF sequence

Support

For assistance with your telephony integration:

• SIP Trunk Configuration : Contact Digital Samba support

• Platform Documentation: docs.digitalsamba.com

• API Reference: developer.digitalsamba.com

• Sinch Middleware demo middleware: https://github.com/digitalsamba/sinch-conference-middleware

---

Appendix: Example Application Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                         Middleware Application                           │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────────┐   │
│  │  Voice API      │    │  Conference     │    │  Digital Samba      │   │
│  │  Event Handler  │    │  Manager        │    │  Client             │   │
│  │                 │    │                 │    │                     │   │
│  │ /voice-events   │───▶│ • Create conf   │───▶│ • Phone user join   │   │
│  │                 │    │ • Validate PIN  │    │ • Phone user leave  │   │
│  │ • ICE callback  │    │ • Route caller  │    │ • Raise/lower hand  │   │
│  │ • DTMF input    │    │ • Track SIP     │    │                     │   │
│  │ • Call ended    │    │ • Track callers │    │                     │   │
│  └─────────────────┘    └─────────────────┘    └─────────────────────┘   │
│           │                      │                        ▲              │
│           │                      │                        │              │
│           ▼                      ▼                        │              │
│  ┌─────────────────────────────────────────────────────────────────┐     │
│  │                          Database                                 │   │
│  │                                                                   │   │
│  │  conferences: {room_id, voice_conf_id, caller_pins[], sip_pin}  │     │
│  │  active_calls: {call_id, conf_id, phone_number, is_sip}         │     │
│  └─────────────────────────────────────────────────────────────────┘     │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐                                                     │
│  │  DS Webhook     │◀────── Digital Samba webhook events                 │
│  │  Handler        │        (mute, unmute, session events)               │
│  │                 │                                                     │
│  │ /ds-webhooks    │───────▶ Voice API (mute participant, etc.)         │
│  └─────────────────┘                                                     │
└──────────────────────────────────────────────────────────────────────────┘

Data Flow Summary

1. Incoming Call → Voice API → Your App → Validate PIN → Join Conference

2. SIP Connection → Voice API Conference → Audio Bridge → Digital Samba Room

3. Phone User Joins → Your App → Digital Samba API (phone-participants-joined)

4. Moderator Mutes → Digital Samba → Webhook → Your App → Voice API Mute

5. Phone User Leaves → Voice API → Your App → Digital Samba API (phone-participants-left)