neo/docs/SOFTPHONE_QUICK_START.md

Softphone Quick Start Guide

Setup (5 minutes)

1. Configure Twilio

1. Create a Twilio account at https://www.twilio.com
2. Get your credentials:
   • Account SID (starts with AC...)
   • Auth Token
   • Purchase a phone number
3. Configure webhook URLs in Twilio Console:
   • Voice webhook: https://your-domain.com/api/voice/twiml/inbound
   • Status callback: https://your-domain.com/api/voice/webhook/status

2. Configure OpenAI (Optional for AI features)

1. Get OpenAI API key from https://platform.openai.com
2. Ensure you have access to Realtime API (beta feature)

3. Add Credentials to Platform

1. Log into your tenant
2. Navigate to Settings → Integrations
3. Fill in Twilio section:
   • Account SID
   • Auth Token
   • Phone Number (format: +1234567890)
4. Fill in OpenAI section (optional):
   • API Key
   • Model: gpt-4o-realtime-preview (default)
   • Voice: alloy (default)
5. Click Save Configuration

Using the Softphone

Make a Call

1. Click Softphone button in sidebar (phone icon)
2. Enter phone number in E.164 format: +1234567890
3. Click Call or press Enter
4. Wait for connection
5. During call:
   • Click hash icon for DTMF keypad
   • Click microphone to mute/unmute
   • Click red phone to hang up

Receive a Call

1. Softphone automatically connects when logged in
2. Incoming call notification appears with ringtone
3. Click Accept (green button) or Reject (red button)
4. If accepted, call controls appear

AI Features (if OpenAI configured)

• Real-time Transcript: See what's being said live
• AI Suggestions: Get contextual tips during calls
• Smart Actions: AI can search contacts, create tasks automatically

Quick Tips

• ✅ Phone number format: +1234567890 (include country code)
• ✅ Close dialog: Click outside or press Escape
• ✅ Incoming calls work even if dialog is closed
• ✅ Recent calls appear for quick redial
• ❌ Don't forget to save credentials before testing
• ❌ Webhook URLs must be publicly accessible (not localhost)

Troubleshooting

Issue	Solution
"Not connected"	Check credentials in Settings → Integrations
Can't make calls	Verify Twilio Account SID and Auth Token
Can't receive calls	Check Twilio webhook configuration
No AI features	Add OpenAI API key in settings
WebSocket errors	Check browser console, verify backend URL

Testing with Twilio Test Credentials

For development, Twilio provides test credentials:

• Use Twilio test numbers
• No actual calls are made
• Simulate call flows in development

Next Steps

• 📞 Make your first test call
• 🎤 Try the AI transcription feature
• 📊 View call history in Softphone dialog
• ⚙️ Configure call routing (advanced)

Need help? Check /docs/SOFTPHONE_IMPLEMENTATION.md for detailed documentation.