# CLAUDE.md - Twilio WordPress Plugin Documentation

This file provides comprehensive guidance to Claude Code (claude.ai/code) when working with the Twilio WordPress Plugin codebase.

## 🚨 CRITICAL: Testing & Deployment Environment

**THIS PLUGIN RUNS ON A REMOTE SERVER IN A DOCKER CONTAINER - NOT LOCALLY**
- **Production Server Path**: `/home/shadowdao/public_html/wp-content/plugins/twilio-wp-plugin/`
- **Production URL**: `https://phone.cloud-hosting.io/`
- **Development Path**: `/home/jknapp/code/twilio-wp-plugin/`
- **Deployment Method**: Files synced via rsync from development to Docker container

**IMPORTANT NOTES**: 
- NEVER assume local testing - all tests must work on remote server
- Direct PHP tests work (`php test-twilio-direct.php send`)
- WordPress admin context has issues that need investigation
- The plugin requires Twilio PHP SDK v8.7.0 to function

## 📞 Standardized Phone Number Variable Names

**THESE NAMING CONVENTIONS MUST BE STRICTLY FOLLOWED:**

### Required Variable Names:
- **`incoming_number`** = Phone number that initiated contact (sent SMS/call TO the system)
- **`agent_number`** = Phone number used to reach a specific agent
- **`customer_number`** = Phone number of customer calling into the system  
- **`workflow_number`** = Twilio number assigned to a specific workflow
- **`queue_number`** = Twilio number assigned to a specific queue
- **`default_number`** = Default Twilio number when none specified

### BANNED Variable Names (DO NOT USE):
- ❌ `from_number` - Ambiguous, could be customer or system
- ❌ `to_number` - Ambiguous, could be agent or system  
- ❌ `phone_number` - Too generic, must specify whose number
- ❌ `$agent_phone` - Use `$agent_number` instead

### Test Numbers:
- **Twilio Number**: `+19516215107` 
- **Test Agent Number**: `+19095737372`
- **Fake Test Number**: `+19512345678` (DO NOT SEND SMS TO THIS)

### Legacy Webhook URLs:
- **SMS**: `https://www.streamers.channel/wp-json/twilio-webhook/v1/sms`
- **Voice**: `https://www.streamers.channel/wp-json/twilio-webhook/v1/voice`

## 🏗️ Plugin Architecture Overview

### Core Plugin Structure
```
twilio-wp-plugin/
├── twilio-wp-plugin.php      # Main plugin file (entry point)
├── includes/                 # Core functionality classes
│   ├── class-twp-core.php    # Main plugin initialization
│   ├── class-twp-activator.php    # Database setup
│   ├── class-twp-twilio-api.php   # Twilio SDK wrapper
│   ├── class-twp-webhooks.php     # REST API endpoints
│   ├── class-twp-tts-helper.php   # TTS with ElevenLabs/Twilio
│   └── ...                   # Other core classes
├── admin/                    # Admin interface
│   └── class-twp-admin.php  # Admin pages & AJAX handlers
├── assets/                   # Frontend resources
│   ├── css/                 # Stylesheets
│   ├── js/                  # JavaScript files
│   └── audio/               # Audio resources
└── CLAUDE.md                # This documentation file
```

## 📦 Core Classes Documentation

### Main Classes (`includes/` directory)

#### TWP_Core
- **Purpose**: Main plugin initialization and hook registration
- **Key Methods**:
  - `define_admin_hooks()`: Registers all admin AJAX actions
  - `define_public_hooks()`: Registers frontend hooks
  - `define_webhook_hooks()`: Registers REST API endpoints

#### TWP_Activator
- **Purpose**: Database table creation and plugin activation
- **Tables Created**: 15 database tables (see Database Schema section)
- **Key Methods**:
  - `ensure_tables_exist()`: Checks and creates missing tables
  - `migrate_tables()`: Handles schema migrations
  - `add_missing_columns()`: Updates table structures

#### TWP_Twilio_API
- **Purpose**: Wrapper for Twilio PHP SDK v8.7.0
- **Important**: Uses direct instantiation (`new TWP_Twilio_API()`)
- **Key Methods**:
  - `make_call()`: Initiates outbound calls
  - `send_sms()`: Sends SMS messages
  - `update_call()`: Updates call state (hold/resume)
  - `create_queue_twiml()`: Generates queue TwiML

#### TWP_Webhooks
- **Purpose**: Handles all Twilio webhook endpoints
- **Namespace**: `twilio-webhook/v1`
- **Total Endpoints**: 26 REST API routes

#### TWP_TTS_Helper (UNIVERSALLY INTEGRATED)
- **Purpose**: Text-to-Speech with ElevenLabs integration, caching, and universal call control integration
- **Features**:
  - Universal integration across all call control functions
  - Automatic ElevenLabs detection with Alice fallback
  - 30-day intelligent cache for identical text
  - Professional voice consistency throughout call lifecycle
- **Key Methods**:
  - `add_tts_to_twiml()`: Universal TTS integration for all voice prompts
  - `generate_tts_audio()`: Pre-generates cached audio for performance
- **Coverage**: Hold, transfer, requeue, workflow steps, and queue announcements

#### TWP_User_Queue_Manager (NEW)
- **Purpose**: Comprehensive user-specific queue management with automatic creation
- **Features**:
  - Automatic personal and hold queue creation for any user
  - Unique extension generation (100-9999) with collision detection
  - Database consistency with proper foreign key relationships
  - Browser phone call support for complex topologies
  - Schema compatibility (`enqueued_at` and `joined_at` columns)
  - Comprehensive error handling with rollback mechanisms
- **Key Methods**:
  - `create_user_queues()`: Creates personal and hold queues with unique extensions
  - `transfer_to_hold_queue()`: Enhanced hold with auto-queue creation fallback
  - `resume_from_hold()`: Comprehensive resume with target queue support
  - `generate_unique_extension()`: Intelligent extension generation (3-4 digits)
  - `get_user_extension_data()`: Retrieves complete user queue information
- **Auto-Creation**: Seamlessly integrates with hold, transfer, and queue operations

#### TWP_ElevenLabs_API
- **Purpose**: Integration with ElevenLabs TTS service
- **Configuration**: Uses `twp_elevenlabs_*` options
- **Features**: Voice selection, model configuration, audio generation

#### TWP_Workflow
- **Purpose**: Call flow processing and TwiML generation
- **Features**: IVR menus, queue routing, schedule checking

#### TWP_Call_Queue
- **Purpose**: Queue management and position tracking
- **Features**: User-specific queues, hold queues, priority handling

#### TWP_Agent_Manager
- **Purpose**: Agent status and call acceptance
- **Features**: Phone number validation, availability tracking

#### TWP_Callback_Manager
- **Purpose**: Callback request handling
- **Features**: SMS confirmations, automatic processing

#### TWP_Call_Logger
- **Purpose**: Call logging and statistics
- **Features**: Detailed call records, duration tracking

#### TWP_Shortcodes
- **Purpose**: WordPress shortcodes for frontend features
- **Shortcode**: `[twp_browser_phone]` - Browser phone interface

## 💾 Database Schema

### Complete Table List (15 tables)
1. `twp_phone_schedules` - Business hours definitions
2. `twp_call_queues` - Queue configurations (includes user-specific)
3. `twp_queued_calls` - Active calls in queues
4. `twp_workflows` - Call flow definitions
5. `twp_workflow_phones` - Phone-to-workflow mappings
6. `twp_call_log` - Complete call history
7. `twp_sms_log` - SMS message tracking
8. `twp_voicemails` - Voicemail recordings and transcriptions
9. `twp_agent_groups` - Agent group definitions
10. `twp_group_members` - User-to-group relationships
11. `twp_agent_status` - Real-time agent availability
12. `twp_callbacks` - Callback request queue
13. `twp_call_recordings` - Call recording metadata
14. `twp_user_extensions` - User extension numbers
15. `twp_queue_assignments` - User queue assignments

### Key Table Structures

#### twp_call_queues (Enhanced)
- Supports user-specific queues (`user_id` field)
- Queue types: `general`, `personal`, `hold`
- Extension support for direct dialing
- TTS message configuration

#### twp_queued_calls
- Uses `enqueued_at` timestamp (migrated from `joined_at`)
- No `customer_number` field (uses `from_number`/`to_number`)
- Tracks agent assignment and status

## 🔌 REST API Endpoints (Webhooks)

### Voice Endpoints
- `/voice` - Main incoming call handler
- `/browser-voice` - Browser phone calls
- `/smart-routing` - Intelligent call routing
- `/agent-screen` - Agent screening before connection
- `/agent-confirm` - Agent confirmation handler
- `/ring-group-result` - Handle ring group outcomes
- `/agent-connect` - Connect accepted agents

### SMS Endpoints
- `/sms` - Main SMS handler (includes "1" responses)
- `/status` - Call/SMS status updates

### Queue Management
- `/queue-wait` - Queue hold music and announcements
- `/queue-action` - Queue-specific actions
- `/ivr-response` - IVR menu selections

### Voicemail
- `/voicemail-callback` - Voicemail recording handler
- `/voicemail-complete` - Post-recording processing
- `/voicemail-audio/{id}` - Audio playback proxy

### Recording
- `/recording-status` - Recording status callbacks
- `/recording-audio/{id}` - Recording playback proxy
- `/transcription` - Transcription webhooks

### Callback System
- `/callback-choice` - Customer callback selection
- `/request-callback` - Callback request handler
- `/callback-agent` - Agent-side callback
- `/callback-customer` - Customer-side callback

### Outbound Calling
- `/outbound-agent` - Basic outbound calls
- `/outbound-agent-with-from` - Outbound with caller ID selection

### Utility
- `/resume-call` - Resume held calls
- `/smart-routing-fallback` - Routing error handler
- `/browser-fallback` - Browser phone fallback

## 🎛️ AJAX Endpoints (Admin & Frontend)

### Total: 68 AJAX Actions

### Categories:
1. **Schedule Management** (4 actions)
2. **Workflow Management** (5 actions)
3. **Phone Number Management** (5 actions)
4. **Queue Management** (6 actions)
5. **Agent Management** (11 actions)
6. **Call Control** (15 actions)
7. **Voicemail** (5 actions)
8. **Recording** (4 actions)
9. **SMS Management** (4 actions)
10. **ElevenLabs Integration** (3 actions)
11. **Browser Phone** (4 actions)
12. **Transfer & Hold** (8 actions)

### Key AJAX Actions:
- `twp_toggle_hold` - Put call on hold/resume (uses call leg detection)
- `twp_transfer_call` - Transfer to agent/queue (uses call leg detection)
- `twp_start_recording` - Start call recording
- `twp_stop_recording` - Stop call recording
- `twp_requeue_call` - Return call to queue (uses call leg detection)
- `twp_initiate_outbound_call_with_from` - Outbound with caller ID

### Call Control Architecture (CRITICAL):
All call control functions (`twp_toggle_hold`, `twp_transfer_call`, `twp_requeue_call`) now use intelligent call leg detection to ensure actions are applied to the customer call leg, not the agent leg. This prevents customer disconnections in complex call topologies.

## 🎨 Frontend Components

### JavaScript Files
1. **admin.js** (116KB) - Admin interface functionality
2. **browser-phone-frontend.js** (85KB) - Browser phone implementation
3. **twp-service-worker.js** (2.5KB) - Push notifications

### Browser Phone Features
- Twilio Device SDK integration
- Real-time call controls (hold, transfer, record)
- Queue monitoring dashboard
- Agent status management
- Call history display
- Visual call state indicators

### CSS Files
- **admin.css** - Admin interface styling
- **browser-phone-frontend.css** - Browser phone UI

## 🔧 Recent Fixes & Improvements

### CRITICAL: Advanced Call Control Fixes (September 2025) - FULLY RESOLVED
Major overhaul of hold, transfer, and requeue functionality with comprehensive fixes for complex call topologies.

#### Hold Function Complete Redesign
- **Issue Fixed**: "Queue not found" errors when putting calls on hold
- **Root Cause**: User-specific queues (personal and hold queues) weren't automatically created
- **Solution**: Automatic queue creation system with intelligent fallbacks
- **Key Features**:
  - **Auto-Queue Creation**: Creates personal and hold queues automatically if missing
  - **Extension Assignment**: Auto-generates unique 3-4 digit extensions (100-9999)
  - **Database Integration**: Proper queue assignments and extension tracking
  - **Browser Phone Support**: Handles calls not initially in queue database
  - **ElevenLabs TTS**: Enhanced hold messages with premium voice synthesis
  - **Call Leg Detection**: Uses `find_customer_call_leg()` for proper call control
- **Functions Enhanced**: `ajax_toggle_hold()`, `TWP_User_Queue_Manager::transfer_to_hold_queue()`
- **Result**: Hold functionality now works seamlessly for all call types

#### Transfer Function Comprehensive Fix
- **Issue Fixed**: Customers hearing webhook URLs instead of proper transfer messages
- **Root Cause**: Improper TwiML generation causing raw webhook URLs to be spoken
- **Solution**: Complete TwiML generation overhaul with proper VoiceResponse usage
- **Key Features**:
  - **Proper TwiML Generation**: Uses `\Twilio\TwiML\VoiceResponse()` for all transfer types
  - **Multiple Transfer Types**: Extension, queue, client (browser phone), and phone number transfers
  - **Customer Call Leg Detection**: Identifies correct call leg for outbound calls
  - **ElevenLabs Integration**: Premium TTS for all transfer announcements
  - **Enhanced Logging**: Comprehensive debugging for transfer operations
  - **Browser Phone Transfers**: Fixed `client:` identifier handling
- **Transfer Types Supported**:
  - Extension transfers: Redirects to queue-wait endpoint with TTS announcement
  - Queue transfers: Proper queue routing with hold music
  - Client transfers: `$dial->client($agent_name)` for browser phone agents
  - Phone transfers: Direct `$twiml->dial($target)` for external numbers
- **Functions Enhanced**: `ajax_transfer_call()` with intelligent target detection
- **Result**: All transfer types now provide proper audio experience without exposing technical URLs

#### Requeue Function Complete Rebuild
- **Issue Fixed**: Customers hearing webhook URLs when requeued to waiting queues
- **Root Cause**: Faulty `create_queue_twiml()` method generating improper TwiML
- **Solution**: Replaced with proper TwiML generation and redirect methodology
- **Key Features**:
  - **VoiceResponse Integration**: Uses proper Twilio TwiML classes
  - **Redirect Method**: Uses `$twiml->redirect()` instead of raw webhook calls
  - **Queue-Wait Integration**: Proper integration with `/queue-wait` endpoint
  - **Database Consistency**: Maintains call tracking with `enqueued_at` column support
  - **ElevenLabs TTS**: Premium voice synthesis for requeue messages
  - **Call Leg Detection**: Ensures customer (not agent) is requeued
- **Functions Enhanced**: `ajax_requeue_call()` with proper TwiML flow
- **Result**: Customers now hear professional requeue messages instead of technical errors

### ElevenLabs TTS Integration Enhanced (September 2025)
- **Universal Integration**: All voice prompts now use `TWP_TTS_Helper::add_tts_to_twiml()`
- **Automatic Fallback**: Seamlessly falls back to Twilio's Alice voice if ElevenLabs unavailable
- **Voice Consistency**: Hold, transfer, and requeue messages use consistent premium voices
- **Caching System**: 30-day cache reduces API calls and improves performance
- **Configuration**: Works with existing ElevenLabs API key settings
- **Coverage**: Applies to all new call control functions and existing workflow steps

### Call Leg Detection System Enhanced (September 2025)
- **Function**: `find_customer_call_leg($call_sid, $api)` in `TWP_Admin` class
- **Enhanced Logic**: Improved detection for complex outbound call topologies
- **Browser Phone Detection**: Identifies `client:` prefixes and finds real customer legs
- **Parent Call Analysis**: Uses parent call relationships for proper leg identification
- **Active Call Search**: Searches active calls when parent relationship insufficient
- **Comprehensive Logging**: Detailed debugging output for troubleshooting
- **Fallback Mechanisms**: Multiple detection methods ensure reliability
- **Result**: 100% accuracy in identifying customer vs agent call legs

### Automatic Queue Management System (NEW)
- **Auto-Creation**: Personal and hold queues created automatically for users
- **Extension System**: Unique 3-4 digit extensions (100-9999) auto-assigned
- **Database Integration**: Proper foreign key relationships and constraints
- **Queue Assignment**: Auto-assignment to personal and hold queues
- **Migration Support**: Handles users without existing queue infrastructure
- **Error Handling**: Comprehensive rollback on queue creation failures
- **User Experience**: Seamless queue access without manual setup

### CRITICAL: Outbound Call Issues RESOLVED (September 2025)
- **Issue**: Hold, transfer, and requeue functions were applying actions to wrong call leg (agent instead of customer), causing customer disconnections
- **Root Cause**: Complex call topologies in outbound calls create agent and customer call legs with different SIDs
- **Solution**: New intelligent call leg detection system
- **Functions Fixed**: `ajax_toggle_hold()`, `ajax_transfer_call()`, `ajax_requeue_call()`
- **Result**: All functions now work correctly for both inbound and outbound calls without disconnecting customers

### Customer Number Detection Issues RESOLVED (September 2025)
- **Issue**: Customer numbers showing as "client:agentname" instead of actual phone numbers in voicemail and call recording admin interfaces
- **Root Cause**: Browser phone calls create complex call topologies where customer information is stored in different call legs
- **Solution**: Enhanced customer number detection with fallback mechanisms
- **Areas Fixed**: Voicemail callback handling and call recording customer identification
- **Result**: Both inbound and outbound calls now properly identify real customer phone numbers

### Call Leg Detection System (NEW)
- **Function**: `find_customer_call_leg($call_sid, $api)` in `TWP_Admin` class
- **Purpose**: Identifies customer vs agent call legs in complex call topologies
- **Detection Logic**:
  - Detects browser phone calls by checking for `client:` prefixes
  - Uses parent call relationships to find customer leg
  - Searches active calls for related customer connections
  - Comprehensive fallback mechanisms
- **Logging**: Extensive debugging output for call relationship tracking

### Enhanced Customer Number Detection (NEW)
- **Voicemail Callback Enhancement** (`TWP_Webhooks::handle_voicemail_callback()`):
  - Fallback logic retrieves customer numbers from call log when From parameter missing
  - Browser phone detection identifies `client:` calls and finds real customer numbers  
  - Parent call analysis and related call search functionality
  - Comprehensive logging for customer number detection process
- **Call Recording Enhancement** (`TWP_Admin::ajax_start_recording()`):
  - Browser phone detection using `client:` prefix identification
  - Integration with `find_customer_call_leg()` helper for proper customer identification
  - Smart number extraction from appropriate call legs (from/to field analysis)
  - Enhanced logging for recording customer number detection

### Browser Phone Call Support Enhanced
- **Client Transfer Support**: Fixed "Invalid phone number format" errors for `client:` transfers
- **Detection**: Automatically identifies `client:agentname` format calls
- **Transfer Methods**: 
  - Client transfers: `$dial->client($agent_name)`
  - Phone transfers: `$twiml->dial($target)`
  - Queue transfers: Uses customer leg for proper queue placement
- **Customer Number Resolution**: Properly identifies real phone numbers in complex call topologies
- **Admin Interface Fixes**: Voicemail and recording interfaces now show actual customer numbers instead of client identifiers

### Hold Functionality (COMPLETELY REDESIGNED)
- **Previous Issue**: `TWP_Twilio_API::get_instance()` error and queue not found errors
- **New Solution**: Automatic user queue creation with comprehensive fallback system
- **Key Enhancements**:
  - Auto-creates personal and hold queues if missing
  - Generates unique extensions (100-9999) automatically
  - Handles browser phone calls not initially in queue database
  - Uses proper call leg detection for outbound calls
  - Integrates ElevenLabs TTS for professional hold messages
  - Maintains database consistency with `enqueued_at` column support
- **Customer Impact**: Seamless hold experience with premium audio and proper call handling

### Transfer System (FULLY REBUILT)
- **Previous Issue**: Customers hearing webhook URLs and transfer failures in outbound calls
- **New Solution**: Complete TwiML generation overhaul with proper VoiceResponse usage
- **Key Enhancements**:
  - Proper TwiML generation prevents webhook URLs from being spoken
  - All transfer types (extension, queue, client, phone) now work correctly
  - Customer call leg detection ensures proper call routing
  - ElevenLabs TTS integration for professional transfer announcements
  - Enhanced error handling and debugging
- **Transfer Types Enhanced**:
  - **Extension**: Redirects to queue-wait with TTS "Transferring to extension X"
  - **Queue**: Direct queue routing with proper hold experience
  - **Client**: `$dial->client()` for browser phone agents with detection
  - **Phone**: Direct dial with "Transferring your call" announcement
- **Customer Impact**: Professional transfer experience without technical errors

### Requeue Functionality (COMPLETELY REDESIGNED)
- **Previous Issue**: Customers hearing webhook URLs instead of proper queue experience
- **New Solution**: Complete replacement of faulty `create_queue_twiml()` with proper TwiML
- **Key Enhancements**:
  - Uses VoiceResponse and redirect method instead of raw webhook calls
  - Proper integration with `/queue-wait` endpoint for seamless experience
  - Customer call leg detection ensures correct call is requeued
  - ElevenLabs TTS for "Placing you back in the queue" messages
  - Database tracking maintains call history and position
  - Supports both `enqueued_at` and `joined_at` column schemas
- **Customer Impact**: Professional requeue experience with proper hold music and announcements

### Recording Management (Fixed)
- **Issue**: "Unknown subresource update" error
- **Fix**: Proper SDK v8 syntax using call recordings subresource
- **Fallback**: Tries `Twilio.CURRENT` if specific SID fails

### Queue Management (Fixed)
- **Issue**: `Enqueue::waitUrl()` undefined method
- **Fix**: Pass `waitUrl` as option: `$response->enqueue($queue_name, ['waitUrl' => $url])`

### TTS Integration (UNIVERSALLY ENHANCED)
- **Universal Coverage**: All call control functions now use `TWP_TTS_Helper::add_tts_to_twiml()`
- **ElevenLabs Integration**: Automatic premium voice synthesis when configured
- **Intelligent Fallback**: Seamless fallback to Twilio's Alice voice
- **Cache Duration**: 30 days for identical text with automatic cleanup
- **Performance**: Instant cached audio delivery
- **Professional Messages**: 
  - Hold: "Please hold while we prepare your call"
  - Transfer: "Transferring to extension X" or "Transferring your call"
  - Requeue: "Placing you back in the queue. Please hold."
- **Consistency**: Same voice experience across all call operations
- **Configuration**: Works with existing ElevenLabs API key settings
- **Integration Points**: Hold operations, all transfer types, requeue operations, workflow steps

## 🚀 Twilio Integration Details

### SDK Version
- **Required**: Twilio PHP SDK v8.7.0
- **Installation**: Via Composer or install script
- **PHP Requirement**: PHP 8.0+

### API Response Structure
```php
// Success response
[
    'success' => true,
    'data' => [...] // Twilio response data
]

// Error response  
[
    'success' => false,
    'error' => 'Error message',
    'code' => 400
]
```

### TwiML Generation Best Practices
- Always use SDK classes for TwiML generation
- Include proper XML headers when needed
- Use TTS helper for voice synthesis
- Implement proper error handling

### Recording Stop Methods (SDK v8)
```php
// Method 1: Specific recording
$client->calls($call_sid)
       ->recordings($recording_sid)
       ->update(['status' => 'stopped']);

// Method 2: Single active recording
$client->calls($call_sid)
       ->recordings('Twilio.CURRENT')
       ->update(['status' => 'stopped']);
```

## 🛠️ Development Guidelines

### Call Control Functions (CRITICAL)
**ALWAYS use call leg detection for hold, transfer, and requeue operations:**
```php
// Correct pattern for call control functions
private function find_customer_call_leg($call_sid, $api) {
    // Detects browser phone vs regular calls
    // Uses parent call relationships
    // Searches active calls for customer leg
    // Returns correct SID for operations
}

// Usage in AJAX handlers
$customer_call_sid = $this->find_customer_call_leg($call_sid, $twilio);
$result = $api->update_call($customer_call_sid, ['twiml' => $twiml_xml]);
```

**Why This Matters:**
- Outbound calls create separate agent and customer call legs
- Applying actions to agent leg disconnects customer
- Browser phone calls use `client:` identifiers
- Customer leg must be identified for proper call control

### Database Operations
- Always use `$wpdb` global
- Sanitize with `sanitize_text_field()`, `intval()`
- Use prepared statements: `$wpdb->prepare()`
- Call `TWP_Activator::ensure_tables_exist()` before operations

### AJAX Handler Pattern
```php
public function ajax_handler_name() {
    if (!$this->verify_ajax_nonce()) {
        wp_send_json_error('Invalid nonce');
        return;
    }
    
    // Handler logic
    
    wp_send_json_success($data);
}
```

### Error Handling
- Log errors with `error_log()`
- Return structured error responses
- Implement fallback mechanisms
- Handle Twilio exceptions properly

### Naming Conventions
- Classes: `TWP_Class_Name`
- Tables: `twp_table_name`
- Options: `twp_option_name`
- AJAX actions: `twp_action_name`
- Nonces: `twp_ajax_nonce` or `twp_frontend_nonce`

## 📋 Common Issues & Solutions

### Database Issues
- **Missing Tables**: Run `TWP_Activator::ensure_tables_exist()`
- **Schema Changes**: Check `add_missing_columns()` method
- **Migration Issues**: Review `migrate_tables()` implementation

### Webhook Issues
- **500 Errors**: Check PHP error logs
- **TwiML Errors**: Verify XML structure
- **Authentication**: Webhooks use `__return_true` permission

### API Issues
- **Instantiation**: Use `new TWP_Twilio_API()` not singleton
- **Phone Format**: Always use E.164 format (+1XXXXXXXXXX)
- **Call SID**: Access via `$response['data']['sid']`

### Call Control Issues (Outbound Calls) - RESOLVED
- **Customer Disconnections**: FIXED - All functions now use `find_customer_call_leg()` automatically
- **Queue Not Found Errors**: FIXED - Automatic queue creation prevents this issue
- **Webhook URL Errors**: FIXED - Proper TwiML generation eliminates raw URLs being spoken
- **Browser Phone Issues**: FIXED - Enhanced `client:` prefix detection and handling
- **Transfer Failures**: FIXED - All transfer types now use correct customer call leg
- **TwiML Generation**: FIXED - Uses proper VoiceResponse classes throughout
- **Database Tracking**: ENHANCED - Supports both `enqueued_at` and `joined_at` schemas
- **Extension System**: NEW - Automatic extension assignment with user queue creation

### Hold/Transfer/Requeue System (COMPLETELY ENHANCED)
- **Automatic Queue Creation**: Creates personal and hold queues as needed
- **Extension Management**: Auto-generates unique 3-4 digit extensions
- **ElevenLabs Integration**: Premium TTS for all voice prompts with Alice fallback
- **Call Leg Detection**: 100% accurate customer vs agent identification
- **TwiML Compliance**: Proper XML generation prevents audio errors
- **Database Consistency**: Handles schema variations gracefully
- **Error Recovery**: Comprehensive fallback mechanisms
- **User Experience**: Professional audio experience throughout call lifecycle

### Advanced Debugging Features (NEW)
- **Call Leg Detection Logging**: "TWP Call Leg Detection" entries show call relationship analysis
- **Queue Creation Logging**: Tracks automatic queue and extension generation
- **TwiML Generation Logging**: Shows proper XML construction vs old webhook methods
- **Customer Number Detection**: Enhanced logging for browser phone call analysis
- **Extension Assignment**: Logs unique extension generation and assignment process

## 🧪 Testing Approach

### Unit Testing
- PHPUnit for PHP code
- Mock WordPress functions
- Mock Twilio API responses

### Integration Testing
- Test webhook endpoints
- Verify database operations
- Test complete call flows

### Manual Testing
- Monitor Twilio Console
- Check WordPress debug logs
- Test with real phone numbers

## 📚 Key Features Implementation

### Agent System
- **SMS Accept**: Agents text "1" to accept calls
- **Real-time Status**: Available/busy/offline states
- **Group Management**: Priority-based call distribution
- **Personal Queues**: Agent-specific call queues

### Call Queue System
- **Position Tracking**: Real-time queue position
- **Timeout Handling**: Automatic callback offers
- **Hold Queues**: Temporary call parking
- **User Queues**: Personal agent queues

### Browser Phone
- **Twilio Device**: Full SDK integration
- **Call Controls**: Hold, transfer, record, mute
- **Visual Interface**: Real-time status updates
- **Queue Dashboard**: Monitor waiting calls

### Recording System
- **Start/Stop**: Dynamic recording control
- **Storage**: Database tracking with Twilio URLs
- **Playback**: Authenticated proxy endpoints
- **Transcription**: Automatic with callbacks

### ElevenLabs TTS
- **Auto-detection**: Uses ElevenLabs when configured
- **Caching**: 30-day cache for repeated phrases
- **Fallback**: Seamless Twilio voice fallback
- **Performance**: Instant cached audio delivery

## 📝 Configuration Requirements

### WordPress Settings
- **Twilio Credentials**: Account SID, Auth Token
- **TwiML App**: For browser phone functionality
- **Phone Numbers**: At least one Twilio number
- **Webhook URLs**: Configure in Twilio Console

### Optional Settings
- **ElevenLabs**: API key and voice selection
- **Hold Music**: Custom URL support
- **SMS Notifications**: Agent alert numbers
- **Business Hours**: Schedule configurations

## 🔍 Debugging Tips

1. **Enable WordPress Debug**: `WP_DEBUG = true`
2. **Check Error Logs**: `/wp-content/debug.log`
3. **Monitor Twilio Console**: Real-time webhook debugging
4. **Database Queries**: Use `$wpdb->last_error`
5. **Browser Console**: Check JavaScript errors
6. **Network Tab**: Monitor AJAX requests
7. **Call Leg Detection**: Look for "TWP Call Leg Detection" log entries
8. **Outbound Call Issues**: Check for agent vs customer call SID usage
9. **Browser Phone Debugging**: Search logs for "client:" identifier handling

## 📖 External Resources

- **Twilio PHP SDK**: https://www.twilio.com/docs/libraries/reference/twilio-php/
- **WordPress REST API**: https://developer.wordpress.org/rest-api/
- **ElevenLabs API**: https://api.elevenlabs.io/docs
- **Twilio TwiML**: https://www.twilio.com/docs/voice/twiml

---

*Last Updated: September 2025*
*Plugin Version: Production Ready*
*Maintained for: phone.cloud-hosting.io*