Add twilio softphone with integrated AI assistant

DEBUG_INCOMING_CALL.md

@@ -0,0 +1,83 @@
+# Debugging Incoming Call Issue
+
+## Current Problem
+- Hear "Connecting to your call" message (TwiML is executing)
+- No ring on mobile after "Connecting" message
+- Click Accept button does nothing
+- Call never connects
+
+## Root Cause Hypothesis
+The Twilio Device SDK is likely **NOT receiving the incoming call event** from Twilio's Signaling Server. This could be because:
+
+1. **Identity Mismatch**: The Device's identity (from JWT token) doesn't match the `<Client>ID</Client>` in TwiML
+2. **Device Not Registered**: Device registration isn't completing before the call arrives
+3. **Twilio Signaling Issue**: Device isn't connected to Twilio Signaling Server
+
+## How to Debug
+
+### Step 1: Check Device Identity in Console
+When you open the softphone dialog, **open Browser DevTools Console (F12)**
+
+You should see logs like:
+```
+Token received, creating Device...
+Token identity: e6d45fa3-a108-4085-81e5-a8e05e85e6fb
+Token grants: {voice: {...}}
+Registering Twilio Device...
+✓ Twilio Device registered - ready to receive calls
+Device identity: e6d45fa3-a108-4085-81e5-a8e05e85e6fb
+Device state: ready
+```
+
+**Note the Device identity value** - e.g., "e6d45fa3-a108-4085-81e5-a8e05e85e6fb"
+
+### Step 2: Check Backend Logs
+When you make an inbound call, look for backend logs showing:
+
+```
+╔════════════════════════════════════════╗
+║ === INBOUND CALL RECEIVED ===
+╚════════════════════════════════════════╝
+...
+Client IDs to dial: e6d45fa3-a108-4085-81e5-a8e05e85e6fb
+First Client ID format check: "e6d45fa3-a108-4085-81e5-a8e05e85e6fb" (length: 36)
+```
+
+### Step 3: Compare Identities
+The Device identity from frontend console MUST MATCH the Client ID from backend logs.
+
+**If they match**: The issue is with Twilio Signaling or Device SDK configuration
+**If they don't match**: We found the bug - identity mismatch
+
+### Step 4: Monitor Incoming Event
+When you make the inbound call, keep watching the browser console for:
+
+```
+🔔 Twilio Device INCOMING event received: {...}
+```
+
+**If this appears**: The Device SDK IS receiving the call, so the Accept button issue is frontend
+**If this doesn't appear**: The Device SDK is NOT receiving the call, so it's an identity/registration issue
+
+## What Changed
+- Frontend now relies on **Twilio Device SDK `incoming` event** (not Socket.IO) for showing incoming call
+- Added comprehensive logging to Device initialization
+- Added logging to Accept button handler
+- Backend logs Device ID format for comparison
+
+## Next Steps
+
+1. Make an inbound call
+2. Check browser console for the 5 logs above
+3. Check backend logs for Client ID
+4. Look for "🔔 Twilio Device INCOMING event" in browser console
+5. Try clicking Accept and watch console for "📞 Accepting call" logs
+6. Report back with:
+   - Device identity from console
+   - Client ID from backend logs
+   - Whether "🔔 Twilio Device INCOMING event" appears
+   - Whether any accept logs appear
+
+## Important Files
+- Backend: `/backend/src/voice/voice.controller.ts` (lines 205-210 show Client ID logging)
+- Frontend: `/frontend/composables/useSoftphone.ts` (Device initialization and incoming handler)