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