neo/docs/SOFTPHONE_CHECKLIST.md

Softphone Configuration Checklist

Pre-Deployment Checklist

Backend Configuration

• Environment Variables Set

  • BACKEND_URL - Public URL of backend (e.g., https://api.yourdomain.com)
  • ENCRYPTION_KEY - 32-byte hex key for encrypting credentials
  • Database connection URLs configured

• Dependencies Installed

  cd backend
  npm install
  

• Migrations Run

  # Generate Prisma client
  npx prisma generate --schema=./prisma/schema-central.prisma
  
  # Run tenant migrations (creates calls table)
  npm run migrate:all-tenants
  

• Build Succeeds

  npm run build
  

Frontend Configuration

• Environment Variables Set

  • VITE_BACKEND_URL - Backend URL (e.g., https://api.yourdomain.com)

• Dependencies Installed

  cd frontend
  npm install
  

• Build Succeeds

  npm run build
  

Twilio Setup

• Account Created

  • Sign up at https://www.twilio.com
  • Verify account (phone/email)

• Credentials Retrieved

  • Account SID (starts with AC...)
  • Auth Token (from Twilio Console)

• Phone Number Purchased

  • Buy a phone number in Twilio Console
  • Note the phone number in E.164 format (e.g., +1234567890)

• Webhooks Configured

  • Go to Phone Numbers → Active Numbers → [Your Number]
  • Voice Configuration:
    • A CALL COMES IN: Webhook
    • URL: https://your-backend-url.com/api/voice/twiml/inbound
    • HTTP: POST
  • Status Callback:
    • URL: https://your-backend-url.com/api/voice/webhook/status
    • HTTP: POST

• Media Streams (Optional)

  • Enable Media Streams in Twilio Console
  • Note: Full implementation pending

OpenAI Setup (Optional)

• API Key Obtained

  • Sign up at https://platform.openai.com
  • Create API key in API Keys section
  • Copy key (starts with sk-...)

• Realtime API Access

  • Ensure account has access to Realtime API (beta feature)
  • Contact OpenAI support if needed

• Model & Voice Selected

  • Model: gpt-4o-realtime-preview (default)
  • Voice: alloy, echo, fable, onyx, nova, or shimmer

Tenant Configuration

• Log into Tenant

  • Use tenant subdomain (e.g., acme.yourdomain.com)
  • Login with tenant user account

• Navigate to Integrations

  • Go to Settings → Integrations (create page if doesn't exist)

• Configure Twilio

  • Enter Account SID
  • Enter Auth Token
  • Enter Phone Number (with country code)
  • Click Save Configuration

• Configure OpenAI (Optional)

  • Enter API Key
  • Set Model (or use default)
  • Set Voice (or use default)
  • Click Save Configuration

Testing

• WebSocket Connection

  • Open browser DevTools → Network → WS
  • Click "Softphone" button in sidebar
  • Verify WebSocket connection to /voice namespace
  • Check for "Connected" status in softphone dialog

• Outbound Call

  • Enter a test phone number
  • Click "Call"
  • Verify call initiates
  • Check call appears in Twilio Console → Logs
  • Verify call status updates in UI

• Inbound Call

  • Call your Twilio number from external phone
  • Verify incoming call notification appears
  • Verify ringtone plays
  • Click "Accept"
  • Verify call connects

• AI Features (if OpenAI configured)

  • Make a call
  • Speak during call
  • Verify transcript appears in real-time
  • Check for AI suggestions
  • Test AI tool calls (if configured)

• Call History

  • Make/receive multiple calls
  • Open softphone dialog
  • Verify recent calls appear
  • Click recent call to redial

Production Readiness

• Security

  • HTTPS enabled on backend
  • WSS (WebSocket Secure) working
  • CORS configured correctly
  • Environment variables secured

• Monitoring

  • Backend logs accessible
  • Error tracking setup (e.g., Sentry)
  • Twilio logs monitored

• Scalability

  • Redis configured for BullMQ (future)
  • Database connection pooling configured
  • Load balancer if needed

• Documentation

  • User guide shared with team
  • Twilio credentials documented securely
  • Support process defined

Verification Commands

# Check backend build
cd backend && npm run build

# Check frontend build  
cd frontend && npm run build

# Verify migrations
cd backend && npm run migrate:status

# Test WebSocket (after starting backend)
# In browser console:
const socket = io('http://localhost:3000/voice', {
  auth: { token: 'YOUR_JWT_TOKEN' }
});
socket.on('connect', () => console.log('Connected!'));

Common Issues & Solutions

Issue	Check	Solution
"Not connected"	WebSocket URL	Verify BACKEND_URL in frontend .env
Build fails	Dependencies	Run npm install again
Twilio errors	Credentials	Re-enter credentials in settings
No AI features	OpenAI key	Add API key in integrations
Webhook 404	URL format	Ensure /api/voice/... prefix
HTTPS required	Twilio webhooks	Deploy with HTTPS or use ngrok for testing

Post-Deployment Tasks

• Train users on softphone features
• Monitor call quality and errors
• Collect feedback for improvements
• Plan for scaling (queue system, routing)
• Review call logs for insights

Support Resources

• Twilio Docs: https://www.twilio.com/docs
• OpenAI Realtime API: https://platform.openai.com/docs/guides/realtime
• Project Docs: /docs/SOFTPHONE_IMPLEMENTATION.md
• Quick Start: /docs/SOFTPHONE_QUICK_START.md

---

Last Updated: January 3, 2026 Checklist Version: 1.0