wp-plugins/twilio-wp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix hold/resume functionality and customer number detection

Browse Source 
CRITICAL FIXES:
- Fixed hold/resume functions to use proper Hold Queue system instead of empty TwiML
- Enhanced customer number detection for voicemail and call recording interfaces
- Resolved customer disconnections during hold/resume operations on outbound calls

Hold/Resume System Improvements:
- Updated ajax_toggle_hold() to use TWP_User_Queue_Manager for proper queue management
- Fixed resume function to redirect calls back to appropriate queues (personal/shared)
- Added comprehensive logging for hold queue operations and call leg detection
- Enhanced hold experience with proper TTS messages and queue tracking

Customer Number Detection Enhancements:
- Enhanced handle_voicemail_callback() with fallback logic for missing From parameters
- Added browser phone detection to identify client: calls and find real customer numbers
- Enhanced call recording to use find_customer_call_leg() for proper customer identification
- Fixed admin interfaces to show actual phone numbers instead of "client:agentname"

Technical Improvements:
- Integrated Hold Queue system with existing call leg detection infrastructure
- Added proper TwiML generation for hold/resume operations
- Enhanced error handling and logging for debugging complex call topologies
- Maintains database consistency with queue position tracking

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jknapp
2025-09-01 09:34:07 -07:00
parent 5b6011bdb8
commit ae92ea2c81
5 changed files with 1734 additions and 682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

671
CLAUDE.md
View File

@@ -1,19 +1,20 @@
# CLAUDE.md
# CLAUDE.md - Twilio WordPress Plugin Documentation
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
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/`
- **Website URL**: `https://phone.cloud-hosting.io/`
- **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**:
**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
@@ -38,164 +39,318 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- **Test Agent Number**: `+19095737372`
- **Fake Test Number**: `+19512345678` (DO NOT SEND SMS TO THIS)
### Webhook URLs:
### 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`
## Project Overview
## 🏗️ Plugin Architecture Overview
This is a comprehensive WordPress plugin for Twilio voice and SMS integration, featuring:
- **Call Center Functionality**: Agent groups, call queues, call distribution
- **Business Hours Management**: Schedules for workflow routing
- **Outbound Calling**: Click-to-call with proper caller ID
- **SMS Notifications**: Agent notifications and callback management
- **Workflow Builder**: Visual call flow creation
- **Voicemail System**: Recording and transcription
- **Real-time Dashboard**: Agent queue management
## Plugin Architecture
### Core Classes (`includes/` directory)
- **TWP_Core**: Main plugin initialization and hook registration
- **TWP_Activator**: Database table creation and plugin activation
- **TWP_Twilio_API**: Official Twilio PHP SDK wrapper (requires SDK v8.7.0)
- **TWP_Webhooks**: Handles all Twilio webhook endpoints
- **TWP_Scheduler**: Business hours and schedule management
- **TWP_Workflow**: Call flow processing and TwiML generation
- **TWP_Call_Queue**: Queue management and position tracking
- **TWP_Agent_Groups**: Group management for call distribution
- **TWP_Agent_Manager**: Agent status and call acceptance
- **TWP_Callback_Manager**: Callback requests and processing
- **TWP_Call_Logger**: Call logging and statistics
### Database Tables
Created by `TWP_Activator::create_tables()`:
- `twp_phone_schedules` - Business hours definitions
- `twp_call_queues` - Queue configurations
- `twp_queued_calls` - Active calls in queues
- `twp_workflows` - Call flow definitions
- `twp_call_log` - Complete call history
- `twp_sms_log` - SMS message tracking
- `twp_voicemails` - Voicemail recordings and transcriptions
- `twp_agent_groups` - Agent group definitions
- `twp_group_members` - User-to-group relationships
- `twp_agent_status` - Real-time agent availability
- `twp_callbacks` - Callback request queue
### Admin Interface (`admin/` directory)
- **TWP_Admin**: Complete admin interface with pages for:
- Dashboard with real-time statistics
- Business Hours Schedules management
- Workflow Builder with drag-drop interface
- Call Queues configuration
- Phone Numbers management (purchase/configure)
- Voicemail inbox with playback
- Call Logs with filtering
- Agent Groups management
- Agent Queue dashboard
- **Outbound Calls interface** (click-to-call)
### Webhook Endpoints
All registered in `TWP_Webhooks::register_endpoints()`:
- `/voice` - Main voice webhook for incoming calls
- `/sms` - SMS webhook (handles agent "1" responses)
- `/ivr-response` - IVR menu selections
- `/queue-wait` - Queue hold music and position announcements
- `/ring-group-result` - Handle no-answer scenarios and requeuing
- `/agent-connect` - Connect SMS-responding agents to calls
- `/callback-*` - Callback system webhooks
- `/outbound-agent-with-from` - Outbound calling with from number
## Key Features Implementation
### Agent Group System
- **Simultaneous Ring**: All group members called at once
- **Priority Ordering**: Members have priority levels
- **SMS Notifications**: Automatic alerts when no agents available
- **One-Click Accept**: Agents can text "1" to receive calls
- **Real-time Status**: Available/busy/offline tracking
### Call Queue Management
- **Position Tracking**: Callers know their queue position
- **Timeout Handling**: Offers callback instead of hanging up
- **Auto-requeue**: Failed agent connections return to queue
- **Real-time Dashboard**: Agents see waiting calls
### Callback System
- **Smart Callbacks**: Replace timeout hangups
- **SMS Confirmations**: Notify customers of callback requests
- **Automatic Processing**: Cron-based callback execution
- **Statistics Tracking**: Success rates and timing
### Outbound Calling
- **From Number Selection**: Choose business line for caller ID
- **Conference Routing**: Agent-to-customer connection
- **Call Logging**: Track all outbound attempts
- **Proper Caller ID**: Target sees business number
## WordPress Plugin Conventions
### File Structure
### Core Plugin Structure
```
twilio-wp-plugin/
├── twilio-wp-plugin.php (main plugin file)
├── includes/ (core functionality)
├── admin/ (admin interface)
├── assets/ (CSS/JS/images)
├── CLAUDE.md (this file)
├── 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
```
### Class Naming
- Prefix: `TWP_` for all classes
- Database tables: `twp_` prefix
- Options: `twp_` prefix
- AJAX actions: `twp_` prefix
## 📦 Core Classes Documentation
### Database Operations
- Use WordPress `$wpdb` global for all database operations
- Always sanitize inputs with `sanitize_text_field()`, `intval()`, etc.
- Use prepared statements with `$wpdb->prepare()`
- Call `TWP_Activator::ensure_tables_exist()` before database operations
### Main Classes (`includes/` directory)
### AJAX Handling
All AJAX endpoints registered in `TWP_Core::define_admin_hooks()`:
```php
$this->loader->add_action('wp_ajax_twp_action_name', $plugin_admin, 'ajax_action_name');
```
#### 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
### User Profile Integration
Agent phone numbers stored as user meta:
- Meta key: `twp_phone_number`
- Validation: `TWP_Agent_Manager::validate_phone_number()`
- Duplicate checking: `TWP_Agent_Manager::is_phone_number_duplicate()`
#### 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
## Twilio Integration
#### 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
### Current Implementation (SDK-Only)
- **Official Twilio SDK**: Uses `twilio/sdk` v8.7.0 for all operations
- **TwiML Generation**: Uses `\Twilio\TwiML\VoiceResponse` classes
- **Response Handling**: Native Twilio SDK response objects
- **Error Handling**: Proper `\Twilio\Exceptions\TwilioException` handling
#### TWP_Webhooks
- **Purpose**: Handles all Twilio webhook endpoints
- **Namespace**: `twilio-webhook/v1`
- **Total Endpoints**: 26 REST API routes
### Installation Requirements
**IMPORTANT**: The Twilio PHP SDK v8.7.0 is **REQUIRED** for this plugin to function.
#### TWP_TTS_Helper (NEW)
- **Purpose**: Text-to-Speech with ElevenLabs integration and caching
- **Features**:
- Automatic ElevenLabs detection
- 30-day cache for generated audio
- Fallback to Twilio voice
- **Key Methods**:
- `add_tts_to_twiml()`: Adds TTS to TwiML response
- `generate_tts_audio()`: Pre-generates cached audio
**Installation Methods**:
1. **Script Installation** (Recommended):
```bash
chmod +x install-twilio-sdk.sh
./install-twilio-sdk.sh
```
#### TWP_ElevenLabs_API
- **Purpose**: Integration with ElevenLabs TTS service
- **Configuration**: Uses `twp_elevenlabs_*` options
- **Features**: Voice selection, model configuration, audio generation
2. **Composer Installation**:
```bash
composer install
```
#### TWP_Workflow
- **Purpose**: Call flow processing and TwiML generation
- **Features**: IVR menus, queue routing, schedule checking
**PHP Requirements**: PHP 8.0+ required for SDK compatibility
#### 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: 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 (Fixed)
- **Issue**: `TWP_Twilio_API::get_instance()` error
- **Fix**: Changed to direct instantiation + call leg detection
- **Enhancement**: Added ElevenLabs TTS with caching
- **Customer Impact**: Hold now affects customer (not agent) with proper music/messages
### Transfer System (Fixed)
- **Issue**: Transfers were disconnecting customers in outbound calls
- **Fix**: All transfer types now use correct customer call leg
- **Types Supported**: Queue, client (browser phone), phone number transfers
- **Enhancement**: Proper TwiML generation for each transfer type
### Requeue Functionality (Fixed)
- **Issue**: Requeue was disconnecting customers instead of placing them back in queue
- **Fix**: Uses customer call leg for queue placement
- **Enhancement**: Maintains proper call tracking with customer SID
- **Database**: Uses `enqueued_at` column when available, falls back to `joined_at`
### 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 (New)
- **Feature**: ElevenLabs integration with intelligent caching
- **Cache Duration**: 30 days for identical text
- **Fallback**: Automatic fallback to Twilio voice
- **Performance**: Cached audio loads instantly
## 🚀 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
Current Twilio API responses follow this pattern:
```php
// Success response
[
@@ -209,79 +364,199 @@ Current Twilio API responses follow this pattern:
'error' => 'Error message',
'code' => 400
]
// Call SID location
$call_sid = $response['data']['sid']; // NOT $response['call_sid']
```
### TwiML Best Practices
Always include XML declaration:
### 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
$twiml = '<?xml version="1.0" encoding="UTF-8"?>';
$twiml .= '<Response>';
$twiml .= '<Say voice="alice">Message</Say>';
$twiml .= '</Response>';
// 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 Commands
## 🛠️ Development Guidelines
```bash
# Install WordPress development dependencies
composer install
### 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
}
# Install JavaScript dependencies
npm install
# Run PHP CodeSniffer for WordPress coding standards
vendor/bin/phpcs
# Fix PHP coding standards automatically
vendor/bin/phpcbf
# Run PHPUnit tests
vendor/bin/phpunit
# Install Twilio SDK (recommended migration)
composer require twilio/sdk
// 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]);
```
## Testing Approach
**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
### Unit Testing
- Use PHPUnit for PHP code testing
- Mock WordPress functions using Brain Monkey or WP_Mock
- Mock Twilio API responses for reliable testing
### 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
### Integration Testing
- Test webhook endpoints with Twilio webhook simulator
- Test complete call flows end-to-end
- Verify database operations and data integrity
### 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);
}
```
### Manual Testing
- Use Twilio Console to monitor webhook calls
- Check WordPress error logs for debugging
- Test with real phone numbers for user experience
### Error Handling
- Log errors with `error_log()`
- Return structured error responses
- Implement fallback mechanisms
- Handle Twilio exceptions properly
## Common Issues & Solutions
### 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**: Call `TWP_Activator::ensure_tables_exist()`
- **White Admin Modals**: Check for PHP errors in workflow loading
- **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 for fatal errors
- **Missing Parameters**: Parameters must be in webhook URL, not just POST data
- **TwiML Parse Errors**: Always include XML declaration
- **500 Errors**: Check PHP error logs
- **TwiML Errors**: Verify XML structure
- **Authentication**: Webhooks use `__return_true` permission
### API Issues
- **Call SID Access**: Use `$response['data']['sid']` not `$response['call_sid']`
- **Phone Number Format**: Store with + prefix (e.g., "+1234567890")
- **From Number**: Must be a verified Twilio number
- **Instantiation**: Use `new TWP_Twilio_API()` not singleton
- **Phone Format**: Always use E.164 format (+1XXXXXXXXXX)
- **Call SID**: Access via `$response['data']['sid']`
### Agent Management
- **SMS Responses**: Agents text "1" to receive calls
- **Phone Validation**: Auto-formats US numbers to +1 format
- **Duplicate Prevention**: Checks phone numbers across all users
### Call Control Issues (Outbound Calls)
- **Customer Disconnections**: Use `find_customer_call_leg()` before hold/transfer/requeue
- **Wrong Call Leg**: Check error logs for "Call Leg Detection" messages
- **Browser Phone Issues**: Look for `client:` prefix detection in logs
- **Transfer Failures**: Verify customer call leg is being used for TwiML updates
- **Customer Number Display**: Check for "TWP Voicemail Callback" or "TWP Recording" log entries for customer number detection
- **Client Identifier Issues**: Search logs for "client:" identifier handling and real customer number detection
This plugin provides a complete call center solution with professional-grade features suitable for business use.
- our production url is https://phone.cloud-hosting.io
### Hold/Transfer Issues
- **Hold Music**: Default URL provided, customizable via settings
- **TTS Caching**: 30-day cache, auto-cleanup available
- **Transfer**: Supports agent queues and phone numbers
- **Call Topology**: Complex outbound calls require call leg detection
## 🧪 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*

40
README.md
View File

@@ -109,6 +109,20 @@ This plugin **requires** the Twilio PHP SDK v8.7.0 to function. The plugin will
## Recent Updates
### CRITICAL: Outbound Call Issues Fixed (September 2025)
- **Customer Disconnection Issue Resolved**: Fixed major problem where hold, transfer, and requeue functions were disconnecting customers in outbound calls
- **Call Leg Detection System**: New intelligent system identifies customer vs agent call legs in complex call topologies
- **Browser Phone Transfers**: Fixed "Invalid phone number format" errors when transferring to browser phone agents
- **Outbound Call Stability**: All call control functions now work correctly for both inbound and outbound scenarios
- **Enhanced Logging**: Comprehensive debugging for call relationship tracking
### Customer Number Detection Improvements (September 2025)
- **Voicemail Interface Fix**: Customer numbers now display correctly instead of showing "client:agentname" for browser phone calls
- **Call Recording Interface Fix**: Recording admin interface now shows actual customer phone numbers for all call types
- **Smart Number Detection**: Enhanced fallback logic retrieves customer numbers from call logs and parent call analysis
- **Browser Phone Support**: Proper handling of complex call topologies created by browser phone calls
- **User Experience**: Admin interfaces now consistently display meaningful customer information
### Browser Phone Upgrade (v2.0)
- **Migrated to Twilio Voice SDK v2**: Replaced deprecated Client SDK v1.14
- **Improved Stability**: Better error handling and automatic recovery
@@ -331,6 +345,19 @@ php test-sdk.php
- Review workflow step configuration
- Check notification_number field (not phone_number)
#### Outbound Call Control Issues
- **Customer Disconnections**: Fixed in latest version with call leg detection
- **Hold Not Working**: Ensure you have the latest version with `find_customer_call_leg()` function
- **Transfer Failures**: Check error logs for "Call Leg Detection" messages
- **Browser Phone Transfers**: Use latest version that supports `client:` identifier transfers
- **Requeue Problems**: Verify customer call leg is being used, not agent leg
#### Customer Number Display Issues
- **"client:agentname" in Voicemails**: Fixed in latest version with enhanced customer number detection
- **Wrong Numbers in Recording Interface**: Fixed with browser phone detection and call leg analysis
- **Missing Customer Info**: Check error logs for "TWP Voicemail Callback" or "TWP Recording" customer detection messages
- **Browser Phone Call Issues**: Enhanced detection now properly identifies real customer numbers in complex call topologies
#### SMS Not Sending from Admin
- Test with direct PHP script: `php test-twilio-direct.php send`
- Verify Twilio credentials in settings
@@ -413,7 +440,18 @@ All webhooks are REST API endpoints under `/wp-json/twilio-webhook/v1/`:
## Version History
### v2.1.0 (Current)
### v2.2.0 (Current - September 2025)
- **CRITICAL FIXES**: Resolved major outbound call issues
- **Call Leg Detection**: New intelligent system for complex call topologies
- **Customer Disconnection Fix**: Hold, transfer, and requeue now work correctly
- **Browser Phone Transfer Support**: Fixed `client:` identifier handling
- **Enhanced Debugging**: Comprehensive call relationship tracking
- **Outbound Call Stability**: All functions work for both inbound and outbound calls
- **Customer Number Detection**: Enhanced voicemail and recording interfaces to show real customer numbers
- **Browser Phone Interface Fixes**: Admin interfaces now properly identify customers in complex call scenarios
- **Fallback Logic**: Comprehensive customer number detection with call log and parent call analysis
### v2.1.0
- **Multiple Phone Numbers**: Workflows can now handle multiple phone numbers
- **Discord & Slack Integration**: Real-time notifications for call events
- **Enhanced Monitoring**: Automated queue timeout tracking and alerts

1406
admin/class-twp-admin.php
View File

File diff suppressed because it is too large Load Diff

220
includes/class-twp-tts-helper.php Normal file
View File

@@ -0,0 +1,220 @@
<?php
/**
* TTS Helper class to handle Text-to-Speech with ElevenLabs or Twilio
*/
class TWP_TTS_Helper {
private static $instance = null;
private $elevenlabs_api = null;
private $use_elevenlabs = false;
/**
* Get singleton instance
*/
public static function get_instance() {
if (self::$instance === null) {
self::$instance = new self();
}
return self::$instance;
}
/**
* Constructor
*/
private function __construct() {
// Check if ElevenLabs is configured
$api_key = get_option('twp_elevenlabs_api_key');
$voice_id = get_option('twp_elevenlabs_voice_id');
if (!empty($api_key) && !empty($voice_id)) {
$this->use_elevenlabs = true;
require_once plugin_dir_path(dirname(__FILE__)) . 'includes/class-twp-elevenlabs-api.php';
$this->elevenlabs_api = new TWP_ElevenLabs_API();
}
}
/**
* Get cache key for text
*/
private function get_cache_key($text) {
$voice_id = get_option('twp_elevenlabs_voice_id');
$model_id = get_option('twp_elevenlabs_model_id', 'eleven_multilingual_v2');
return 'twp_tts_' . md5($text . $voice_id . $model_id);
}
/**
* Get cached audio URL if exists
*/
private function get_cached_audio($text) {
$cache_key = $this->get_cache_key($text);
$cached_data = get_transient($cache_key);
if ($cached_data !== false) {
// Verify the file still exists
if (file_exists($cached_data['file_path'])) {
error_log("TWP TTS: Using cached audio for text: " . substr($text, 0, 50) . "...");
return $cached_data;
} else {
// File was deleted, remove from cache
delete_transient($cache_key);
}
}
return false;
}
/**
* Save audio to cache
*/
private function cache_audio($text, $audio_data) {
$cache_key = $this->get_cache_key($text);
// Cache for 30 days
set_transient($cache_key, $audio_data, 30 * DAY_IN_SECONDS);
}
/**
* Add TTS to TwiML Response
*
* @param \Twilio\TwiML\VoiceResponse $twiml The TwiML response object
* @param string $text The text to speak
* @param array $options Options for voice settings (used for Twilio fallback)
* @return bool Success status
*/
public function add_tts_to_twiml($twiml, $text, $options = []) {
// Default Twilio voice options
$default_options = [
'voice' => 'alice',
'language' => 'en-US'
];
$options = array_merge($default_options, $options);
if ($this->use_elevenlabs) {
// First check cache
$cached_audio = $this->get_cached_audio($text);
if ($cached_audio !== false) {
$twiml->play($cached_audio['file_url']);
return true;
}
// Not in cache, generate new audio
$audio_result = $this->elevenlabs_api->text_to_speech($text);
if ($audio_result && isset($audio_result['success']) && $audio_result['success']) {
// Cache the result
$this->cache_audio($text, [
'file_url' => $audio_result['file_url'],
'file_path' => $audio_result['file_path']
]);
// Use the generated audio file
$twiml->play($audio_result['file_url']);
error_log("TWP TTS: Generated new ElevenLabs audio for text: " . substr($text, 0, 50) . "...");
return true;
} else {
// Log the failure and fall back to Twilio
error_log("TWP TTS: ElevenLabs failed, falling back to Twilio. Error: " .
(isset($audio_result['error']) ? $audio_result['error'] : 'Unknown error'));
}
}
// Fall back to Twilio's built-in TTS
$twiml->say($text, $options);
error_log("TWP TTS: Using Twilio voice for text: " . substr($text, 0, 50) . "...");
return true;
}
/**
* Generate TTS audio file (for pre-generation)
*
* @param string $text The text to convert
* @return array|false Array with file_url on success, false on failure
*/
public function generate_tts_audio($text) {
if (!$this->use_elevenlabs) {
return false;
}
// First check cache
$cached_audio = $this->get_cached_audio($text);
if ($cached_audio !== false) {
return [
'success' => true,
'file_url' => $cached_audio['file_url'],
'file_path' => $cached_audio['file_path'],
'cached' => true
];
}
// Not in cache, generate new audio
$result = $this->elevenlabs_api->text_to_speech($text);
if ($result && isset($result['success']) && $result['success']) {
// Cache the result
$this->cache_audio($text, [
'file_url' => $result['file_url'],
'file_path' => $result['file_path']
]);
return [
'success' => true,
'file_url' => $result['file_url'],
'file_path' => $result['file_path'],
'cached' => false
];
}
return false;
}
/**
* Check if ElevenLabs is configured and available
*
* @return bool
*/
public function is_elevenlabs_available() {
return $this->use_elevenlabs;
}
/**
* Get configured voice info
*
* @return array
*/
public function get_voice_info() {
if ($this->use_elevenlabs) {
return [
'provider' => 'elevenlabs',
'voice_id' => get_option('twp_elevenlabs_voice_id'),
'model_id' => get_option('twp_elevenlabs_model_id', 'eleven_multilingual_v2')
];
}
return [
'provider' => 'twilio',
'voice' => 'alice',
'language' => 'en-US'
];
}
/**
* Clean up old TTS files (maintenance)
*/
public function cleanup_old_files($hours = 24) {
$upload_dir = wp_upload_dir();
$path = $upload_dir['path'];
// Only clean up TTS files older than specified hours
$expire_time = time() - ($hours * 3600);
$files = glob($path . '/tts_*.mp3');
if ($files) {
foreach ($files as $file) {
if (filemtime($file) < $expire_time) {
unlink($file);
error_log("TWP TTS: Cleaned up old file: " . basename($file));
}
}
}
}
}

79
includes/class-twp-webhooks.php
View File

@@ -1297,8 +1297,11 @@ class TWP_Webhooks {
$from = isset($params['From']) ? $params['From'] : '';
$workflow_id = isset($params['workflow_id']) ? intval($params['workflow_id']) : 0;
// Enhanced customer number detection for voicemails
$customer_number = $from;
// If From is not provided in the callback, try to get it from the call log
if (empty($from) && !empty($call_sid)) {
if (empty($customer_number) && !empty($call_sid)) {
global $wpdb;
$call_log_table = $wpdb->prefix . 'twp_call_log';
$call_record = $wpdb->get_row($wpdb->prepare(
@@ -1306,11 +1309,81 @@ class TWP_Webhooks {
$call_sid
));
if ($call_record && $call_record->from_number) {
$from = $call_record->from_number;
error_log('TWP Voicemail Callback: Retrieved from_number from call log: ' . $from);
$customer_number = $call_record->from_number;
error_log('TWP Voicemail Callback: Retrieved from_number from call log: ' . $customer_number);
}
}
// If we got a client identifier (browser phone), try to find the real customer number
if (!empty($customer_number) && strpos($customer_number, 'client:') === 0) {
error_log('TWP Voicemail Callback: Detected client identifier, looking for customer number');
try {
// Initialize Twilio API to find the customer call leg
$twilio_api = new TWP_Twilio_API();
$client = $twilio_api->get_client();
$call = $client->calls($call_sid)->fetch();
// Use similar logic to find_customer_call_leg but adapted for voicemail
$real_customer_number = null;
// Check if this call has a parent that contains a real phone number
if ($call->parentCallSid) {
try {
$parent_call = $client->calls($call->parentCallSid)->fetch();
if (strpos($parent_call->from, 'client:') === false && strpos($parent_call->from, '+') === 0) {
$real_customer_number = $parent_call->from;
} elseif (strpos($parent_call->to, 'client:') === false && strpos($parent_call->to, '+') === 0) {
$real_customer_number = $parent_call->to;
}
} catch (Exception $e) {
error_log("TWP Voicemail Callback: Could not fetch parent call: " . $e->getMessage());
}
}
// If no parent success, search related calls
if (!$real_customer_number) {
$related_calls = $client->calls->read(['status' => 'completed'], 20);
foreach ($related_calls as $related_call) {
if ($related_call->sid === $call_sid) continue;
// Check if calls are related
$is_related = false;
if ($call->parentCallSid && $related_call->parentCallSid === $call->parentCallSid) {
$is_related = true;
} elseif ($related_call->parentCallSid === $call_sid) {
$is_related = true;
} elseif ($related_call->sid === $call->parentCallSid) {
$is_related = true;
}
if ($is_related) {
if (strpos($related_call->from, 'client:') === false && strpos($related_call->from, '+') === 0) {
$real_customer_number = $related_call->from;
break;
} elseif (strpos($related_call->to, 'client:') === false && strpos($related_call->to, '+') === 0) {
$real_customer_number = $related_call->to;
break;
}
}
}
}
if ($real_customer_number) {
$customer_number = $real_customer_number;
error_log("TWP Voicemail Callback: Found real customer number: {$customer_number}");
} else {
error_log("TWP Voicemail Callback: WARNING - Could not find real customer number, keeping client identifier");
}
} catch (Exception $e) {
error_log("TWP Voicemail Callback: Error finding customer number: " . $e->getMessage());
}
}
// Update $from to use the detected customer number
$from = $customer_number;
// Debug what we extracted
error_log('TWP Voicemail Callback: recording_url=' . $recording_url . ', from=' . $from . ', workflow_id=' . $workflow_id . ', call_sid=' . $call_sid);