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:

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:

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:

// 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:

// 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:

// 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:

// 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:

navigator.userAgent

Should include "Android" and "Chrome"

Check WebRTC Support

// 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:

navigator.vibrate([300, 200, 300])

Tablet should vibrate if supported.

---

Part 6: Advanced Debugging

Monitor Twilio Device Events

In console, add event listeners:

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

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

Test Audio Context Resume

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

Check Token Expiry

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

---

Part 7: Logging Important Information

Collect Debugging Info

Run this in console to get a debug report:

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