twilio-wp-plugin/DEBUGGING-TABLET.md

# Debugging Browser Phone on Android Tablet

This guide explains how to debug the Twilio WordPress Plugin browser phone on Android tablets (Samsung and other devices).

## Prerequisites

- Android tablet with Chrome browser
- USB cable to connect tablet to computer
- Computer with Chrome browser installed
- USB debugging enabled on tablet

---

## Part 1: Enable USB Debugging on Android Tablet

### Step 1: Enable Developer Options

1. Open **Settings** on your Android tablet
2. Scroll down to **About tablet** (or **About device**)
3. Find **Build number** (may be under "Software information")
4. Tap **Build number** 7 times rapidly
5. You'll see a message: "You are now a developer!"

### Step 2: Enable USB Debugging

1. Go back to **Settings**
2. Scroll down to **Developer options** (newly appeared)
3. Toggle **Developer options** to ON
4. Find **USB debugging** in the list
5. Toggle **USB debugging** to ON
6. Confirm the prompt if asked

### Step 3: Trust Your Computer

1. Connect tablet to computer via USB cable
2. Unlock your tablet screen
3. A popup will appear: "Allow USB debugging?"
4. Check **Always allow from this computer**
5. Tap **OK** or **Allow**

---

## Part 2: Connect Chrome DevTools

### On Your Computer

1. Open **Chrome browser** on your computer
2. Navigate to: `chrome://inspect`
3. You should see your tablet device listed under "Remote Target"
4. Wait a few seconds for the device to appear

### Inspect the Browser Phone Page

1. On your tablet, open Chrome and navigate to:
   ```
   https://phone.cloud-hosting.io/wp-admin/admin.php?page=twilio-wp-browser-phone
   ```
2. On your computer's Chrome DevTools (`chrome://inspect`), you'll see the page listed
3. Click **inspect** next to the browser phone page
4. A DevTools window will open showing your tablet's browser

---

## Part 3: Debug Browser Phone Issues

### Check Console Logs

In the **Console** tab, look for key messages:

#### Successful Connection
```
Twilio SDK loaded successfully
Setting up Twilio Device...
Device detection - Android: true, Mobile: true
AudioContext created, state: running
Device registered successfully
Device connection state: connected
```

#### Connection Issues
```
Device not connected, state: disconnected
Failed to register device
Connection error: 31005
```

#### Call Issues
```
Answer button clicked
Device connection state: connected
Accepting call...
Call accepted and connected
```

### Monitor Network Requests

1. Switch to **Network** tab in DevTools
2. Filter by: `twp_` or `twilio`
3. Check for failed requests (red status codes)
4. Look for:
   - `twp_generate_capability_token` - Should return 200
   - `twp_get_phone_numbers` - Should return 200
   - WebSocket connections to Twilio

### Check Device Registration

In the **Console** tab, type:
```javascript
device
```
This shows the current Twilio Device object. Check:
- `device.state` - Should be "registered"
- `device.token` - Should exist (long string)

### Check AudioContext State

In the **Console** tab, type:
```javascript
audioContext
```
Check:
- Should exist (not null)
- `audioContext.state` - Should be "running" (not "suspended")

---

## Part 4: Common Issues & Solutions

### Issue 1: "Device not connected" Error

**Symptoms**: Status shows "Disconnected", calls hang up immediately

**Debugging**:
```javascript
// In console, check:
deviceConnectionState
// Should be: "connected"
```

**Solutions**:
1. Check network connection (try WiFi vs cellular)
2. Refresh the page with cache cleared
3. Check console for token errors
4. Verify Twilio credentials in plugin settings

### Issue 2: Call Hangs Up Immediately When Answered

**Symptoms**: Click "Answer" button, call disconnects instantly

**Debugging**:
```javascript
// Check device state before answering:
deviceConnectionState
// Check for errors in call handler
```

**Look for console errors**:
- `31005` - Connection/network error
- `31201` - ICE connection failure
- `31208` - Media connection error

**Solutions**:
1. Grant microphone permissions (Settings > Site settings > Microphone)
2. Check AudioContext is running: `audioContext.state`
3. Try switching between WiFi and cellular data
4. Clear Chrome cache and reload

### Issue 3: No Sound/Ringtone on Incoming Call

**Symptoms**: Call arrives but no audio plays, no vibration

**Debugging**:
```javascript
// Check audio setup:
ringtoneAudio
audioContext.state
```

**Solutions**:
1. Tap screen to unlock AudioContext (mobile restriction)
2. Check if ringtone file exists (optional, vibration is fallback)
3. Verify device supports Vibration API: `'vibrate' in navigator`
4. Check browser volume settings

### Issue 4: No Browser Notifications

**Symptoms**: No notification when call arrives in background

**Debugging**:
```javascript
// Check notification permission:
Notification.permission
// Should be: "granted"

// Check service worker:
navigator.serviceWorker.controller
// Should exist
```

**Solutions**:
1. Grant notification permission: Settings > Site settings > Notifications
2. Check service worker registration in **Application** tab of DevTools
3. Look for service worker logs in console
4. Reinstall PWA if installed

### Issue 5: Microphone Permission Denied

**Symptoms**: Error message about microphone access

**Solutions**:
1. Chrome Settings > Site settings > Microphone
2. Find `phone.cloud-hosting.io`
3. Change permission to **Allow**
4. Refresh the browser phone page

---

## Part 5: Tablet-Specific Checks

### Check User Agent

In console:
```javascript
navigator.userAgent
```
Should include "Android" and "Chrome"

### Check WebRTC Support

```javascript
// Check getUserMedia support:
navigator.mediaDevices.getUserMedia
// Should be: function

// Check Notification support:
'Notification' in window
// Should be: true

// Check Service Worker support:
'serviceWorker' in navigator
// Should be: true
```

### Check Audio Constraints

Look in console for:
```
Twilio Device created with audio constraints: {
  echoCancellation: true,
  noiseSuppression: true,
  autoGainControl: true,
  googEchoCancellation: true,
  ...
}
```

### Test Vibration

In console:
```javascript
navigator.vibrate([300, 200, 300])
```
Tablet should vibrate if supported.

---

## Part 6: Advanced Debugging

### Monitor Twilio Device Events

In console, add event listeners:
```javascript
device.on('registered', () => console.log('Device registered!'));
device.on('error', (error) => console.error('Device error:', error));
device.on('incoming', (call) => console.log('Incoming call:', call));
device.on('unregistered', () => console.log('Device unregistered'));
```

### Check Call State During Active Call

```javascript
// When in a call:
currentCall
currentCall.status()
currentCall.parameters
```

### Test Audio Context Resume

```javascript
// Try to resume manually:
audioContext.resume().then(() => {
  console.log('AudioContext state:', audioContext.state);
});
```

### Check Token Expiry

```javascript
// See when token expires:
new Date(tokenExpiry)
```

---

## Part 7: Logging Important Information

### Collect Debugging Info

Run this in console to get a debug report:
```javascript
console.log('=== Browser Phone Debug Report ===');
console.log('User Agent:', navigator.userAgent);
console.log('Device State:', deviceConnectionState);
console.log('Device Registered:', device ? device.state : 'no device');
console.log('AudioContext:', audioContext ? audioContext.state : 'no context');
console.log('Notification Permission:', Notification.permission);
console.log('Service Worker:', navigator.serviceWorker.controller ? 'active' : 'inactive');
console.log('Current Call:', currentCall ? 'in call' : 'no call');
console.log('Token Expiry:', tokenExpiry ? new Date(tokenExpiry) : 'unknown');
```

### Check WordPress AJAX Responses

In **Network** tab:
1. Filter: `admin-ajax.php`
2. Click on request
3. Check **Preview** tab for response
4. Look for `success: true` or error messages

---

## Part 8: Testing Checklist

After fixing issues, test these scenarios:

- [ ] Device shows "Connected" status
- [ ] Can make outbound call successfully
- [ ] Can receive incoming call (see notification)
- [ ] Can answer incoming call without hang-up
- [ ] Ringtone plays or tablet vibrates
- [ ] Call audio is clear (echo cancellation working)
- [ ] Can switch between WiFi and cellular during call
- [ ] Browser notification appears when app in background
- [ ] Service worker logs appear in console
- [ ] No errors in console during call lifecycle
- [ ] Can put call on hold
- [ ] Can transfer call
- [ ] Call timer updates correctly

---

## Troubleshooting Specific Error Codes

### Twilio Error 31005
**Meaning**: WebSocket connection failed

**Causes**:
- Network connectivity issues
- Firewall blocking WebSocket
- Mobile network switching (WiFi ↔ cellular)

**Solutions**:
- Check internet connection
- Try different network
- Wait for ICE restart (enabled in config)

### Twilio Error 31201
**Meaning**: ICE connection failed

**Causes**:
- Restrictive NAT/firewall
- Mobile network issues

**Solutions**:
- Try different network
- Check WebRTC connectivity
- Enable mobile data if on WiFi only

### Twilio Error 31204
**Meaning**: Connection error

**Causes**:
- Media connection setup failed
- Signaling timeout

**Solutions**:
- Refresh page
- Check microphone permissions
- Verify audio constraints applied

### Twilio Error 31208
**Meaning**: Media connection failed

**Causes**:
- Microphone access denied
- Audio device issues

**Solutions**:
- Grant microphone permission
- Check device audio settings
- Restart browser

---

## Additional Resources

- Twilio Voice SDK Errors: https://www.twilio.com/docs/voice/sdks/javascript/errors
- Chrome DevTools Remote Debugging: https://developer.chrome.com/docs/devtools/remote-debugging/
- WebRTC Troubleshooting: https://webrtc.github.io/samples/
- Service Worker Debugging: https://developer.chrome.com/docs/workbox/

---

## Contact & Support

If issues persist after following this guide:

1. Collect debug report (see Part 7)
2. Take screenshots of console errors
3. Note tablet model and Android version
4. Report issue with collected information

**Important Files**:
- Browser phone implementation: `admin/class-twp-admin.php` (lines 7400-8300)
- Service worker: `assets/js/twp-service-worker.js`
- CLAUDE.md: Quick reference guide