# 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**
  ```bash
  cd backend
  npm install
  ```

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

- [ ] **Build Succeeds**
  ```bash
  npm run build
  ```

### Frontend Configuration

- [ ] **Environment Variables Set**
  - [ ] `VITE_BACKEND_URL` - Backend URL (e.g., `https://api.yourdomain.com`)

- [ ] **Dependencies Installed**
  ```bash
  cd frontend
  npm install
  ```

- [ ] **Build Succeeds**
  ```bash
  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

```bash
# 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