neo/docs/TWILIO_SETUP.md

Twilio Setup Guide for Softphone

Prerequisites

• Twilio account with a phone number
• Account SID and Auth Token

Basic Setup (Current - Makes calls but no browser audio)

Currently, the softphone initiates calls through Twilio's REST API, but the audio doesn't flow through the browser. The calls go directly to your mobile device with a simple TwiML message.

Full Browser Audio Setup (Requires additional configuration)

To enable actual softphone functionality where audio flows through your browser's microphone and speakers, you need:

Option 1: Twilio Client SDK (Recommended)

1. Create a TwiML App in Twilio Console

   • Go to https://console.twilio.com/us1/develop/voice/manage/twiml-apps
   • Click "Create new TwiML App"
   • Name it (e.g., "RouteBox Softphone")
   • Set Voice URL to: https://yourdomain.com/api/voice/twiml/outbound
   • Set Voice Method to: POST
   • Save and copy the TwiML App SID

2. Create an API Key

   • Go to https://console.twilio.com/us1/account/keys-credentials/api-keys
   • Click "Create API key"
   • Give it a friendly name
   • Copy both the SID and Secret (you won't be able to see the secret again)

3. Add credentials to Settings > Integrations

   • Account SID (from main dashboard)
   • Auth Token (from main dashboard)
   • Phone Number (your Twilio number)
   • API Key SID (from step 2)
   • API Secret (from step 2)
   • TwiML App SID (from step 1)

Option 2: Twilio Media Streams (Alternative - More complex)

Uses WebSocket to stream audio bidirectionally:

• Requires WebSocket server setup
• More control over audio processing
• Can integrate with OpenAI Realtime API more easily

Current Status

The system works but audio doesn't flow through browser because:

1. Calls are made via REST API only
2. No Twilio Client SDK integration yet
3. TwiML returns simple voice message

To enable browser audio, you need to:

1. Complete the Twilio setup above
2. Implement the frontend Twilio Device connection
3. Modify TwiML to dial the browser client instead of just the phone number

Quick Test (Current Setup)

1. Save your Account SID, Auth Token, and Phone Number in Settings > Integrations
2. Click the phone icon in sidebar
3. Enter a phone number and click "Call"
4. You should receive a call that says "This is a test call from your softphone"

The call works, but audio doesn't route through your browser - it's just a regular phone call initiated by the API.