365 lines
13 KiB
Markdown
365 lines
13 KiB
Markdown
# Twilio WordPress Plugin
|
|
|
|
A comprehensive WordPress plugin for Twilio voice and SMS integration with advanced call center functionality.
|
|
|
|
## ⚠️ IMPORTANT: SDK Required
|
|
|
|
This plugin **requires** the Twilio PHP SDK v8.7.0 to function. The plugin will not work without it.
|
|
|
|
## Quick Installation
|
|
|
|
1. **Install the Twilio SDK** (Required):
|
|
```bash
|
|
chmod +x install-twilio-sdk.sh
|
|
./install-twilio-sdk.sh
|
|
```
|
|
|
|
2. **Test the SDK installation**:
|
|
```bash
|
|
php test-sdk.php
|
|
```
|
|
|
|
3. **Configure Twilio Credentials** in WordPress admin:
|
|
- Go to **Twilio** → **Settings**
|
|
- Enter Account SID and Auth Token
|
|
- Configure default phone numbers
|
|
|
|
4. **Set up Phone Numbers** in Twilio Console:
|
|
- Configure webhook URLs for voice and SMS
|
|
- Voice: `https://yoursite.com/wp-json/twilio-webhook/v1/voice`
|
|
- SMS: `https://yoursite.com/wp-json/twilio-webhook/v1/sms`
|
|
|
|
## Requirements
|
|
|
|
- **PHP 8.0+** (required for Twilio SDK v8.7.0)
|
|
- **WordPress 5.0+**
|
|
- **Twilio Account** with active phone number
|
|
- **curl** and **tar** (for SDK installation)
|
|
|
|
## Key Features
|
|
|
|
### 📞 Call Center Operations
|
|
- **Agent Groups**: Organize agents into groups with priority levels
|
|
- **Call Queues**: Manage incoming calls with position announcements
|
|
- **Smart Routing**: Distribute calls based on availability and schedules
|
|
- **SMS Accept**: Agents can text "1" to accept incoming calls
|
|
- **Queue Notifications**: SMS alerts to designated numbers when calls enter queues
|
|
|
|
### 🌐 Browser Phone (WebRTC)
|
|
- **In-Browser Calling**: Make and receive calls directly from WordPress admin
|
|
- **Twilio Voice SDK v2**: Uses latest SDK for WebRTC functionality
|
|
- **Visual Dialpad**: Click-to-dial interface with DTMF support
|
|
- **Call Controls**: Mute, hold indicators, call timer
|
|
- **Auto-Answer**: Optional automatic call acceptance
|
|
- **Queue Integration**: Accept calls from specific queues
|
|
- **Token Management**: Automatic token refresh for uninterrupted service
|
|
|
|
### 🕒 Business Hours Management
|
|
- **Schedule-based Routing**: Different call flows for business hours vs after-hours
|
|
- **Holiday Support**: Define specific dates for holiday routing
|
|
- **Multiple Schedules**: Create different schedules for departments
|
|
- **After-Hours Actions**: Configurable routing when closed
|
|
|
|
### 🎛️ Workflow Builder
|
|
- **Visual Interface**: Drag-and-drop workflow creation
|
|
- **Step Types**:
|
|
- **Greeting**: Welcome messages with multiple voice options
|
|
- **IVR Menu**: Interactive voice response with digit collection
|
|
- **Call Queue**: Place callers in queue with hold music
|
|
- **Forward**: Route calls to specific numbers
|
|
- **Voicemail**: Record messages with transcription
|
|
- **Schedule Check**: Route based on business hours
|
|
- **Voice Options**:
|
|
- Default Twilio voice (Say)
|
|
- ElevenLabs text-to-speech integration with voice persistence
|
|
- Custom audio file URLs
|
|
- **Smart Voice Loading**: Saved voices display without API calls
|
|
|
|
### 📱 SMS Integration
|
|
- **Agent Notifications**: Automatic SMS alerts when calls arrive
|
|
- **Queue Management**: Agents receive queue status updates
|
|
- **Command System**: Text commands to manage availability
|
|
- **SMS Logging**: Complete history of all SMS interactions
|
|
|
|
### 📊 Real-time Dashboard
|
|
- **Queue Monitor**: Live view of waiting calls
|
|
- **Agent Status**: Track agent availability
|
|
- **Call Statistics**: Performance metrics and reporting
|
|
- **Call Logs**: Detailed history with filtering options
|
|
- **Active Call Display**: Real-time call count monitoring
|
|
|
|
### 🎤 Advanced Features
|
|
- **Voicemail Transcription**: Automatic speech-to-text
|
|
- **Callback System**: Offer callbacks instead of long holds
|
|
- **Outbound Calling**: Click-to-call with proper caller ID
|
|
- **Multiple Phone Numbers**: Support for multiple business lines
|
|
- **Agent Phone Management**: Store and validate agent phone numbers
|
|
- **Duplicate Prevention**: Ensures unique phone numbers per agent
|
|
|
|
## Recent Updates
|
|
|
|
### 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
|
|
- **Token Management**: Auto-refresh tokens before expiration
|
|
- **Enhanced Performance**: Modern WebRTC implementation
|
|
|
|
### Queue System Improvements
|
|
- **Notification Numbers**: Queues now use notification_number field for SMS alerts
|
|
- **No Direct Assignment**: Queues are workflow destinations, not directly assigned to numbers
|
|
- **Better Integration**: Improved queue handling in IVR and workflow steps
|
|
|
|
### Voice Configuration Enhancements
|
|
- **Voice Persistence**: ElevenLabs voices save both ID and name
|
|
- **No Unnecessary API Calls**: Saved voices display immediately without loading
|
|
- **Improved UX**: Load voices only when changing selection
|
|
|
|
### IVR Fixes
|
|
- **Form Field Handling**: Fixed IVR option saving and loading
|
|
- **Queue Selection**: Proper queue routing based on digit selection
|
|
- **Voice Selection**: Fixed voice dropdown persistence issues
|
|
|
|
## How It Works
|
|
|
|
### Call Flow
|
|
1. **Incoming Call** → Twilio webhook triggers
|
|
2. **Workflow Processing** → System loads assigned workflow
|
|
3. **Step Execution** → Each workflow step processes sequentially:
|
|
- Greeting plays welcome message
|
|
- IVR collects user input
|
|
- Schedule check determines routing
|
|
- Queue or forward based on configuration
|
|
4. **Agent Connection** → Call routed to available agent
|
|
5. **Logging** → All interactions logged for reporting
|
|
|
|
### Queue System
|
|
- **Queue Assignment**: Calls routed to queues through workflows
|
|
- **Notification Numbers**: Optional SMS alerts to designated numbers (not agents)
|
|
- **Agent Groups**: Queues linked to agent groups for distribution
|
|
- **Wait Experience**: Configurable hold music and position announcements
|
|
- **Timeout Handling**: Automatic callback offers after timeout
|
|
- **Browser Phone Integration**: Agents can accept queue calls via browser
|
|
|
|
### Agent Management
|
|
- **Phone Number Storage**: Agent numbers stored in WordPress user profiles
|
|
- **Status Tracking**: Available/Busy/Offline states
|
|
- **SMS Commands**: Text "1" to accept calls
|
|
- **Priority Levels**: Agents have priority within groups
|
|
- **Browser Phone Mode**: Option to receive calls in browser or cell phone
|
|
|
|
## Configuration
|
|
|
|
### Initial Setup
|
|
1. **Install Plugin** and activate in WordPress
|
|
2. **Install Twilio SDK** using provided script
|
|
3. **Configure Credentials**:
|
|
- Navigate to **Twilio** → **Settings**
|
|
- Enter Twilio Account SID and Auth Token
|
|
- Set default SMS number for notifications
|
|
- Configure TwiML App SID for browser phone (optional)
|
|
|
|
### Phone Number Setup
|
|
1. **In Twilio Console**:
|
|
- Purchase or select phone number
|
|
- Configure Voice webhook: `https://yoursite.com/wp-json/twilio-webhook/v1/voice`
|
|
- Configure SMS webhook: `https://yoursite.com/wp-json/twilio-webhook/v1/sms`
|
|
- Set method to HTTP POST
|
|
|
|
2. **In WordPress Admin**:
|
|
- Go to **Twilio** → **Phone Numbers**
|
|
- Verify numbers are synchronized
|
|
- Assign workflows to numbers
|
|
|
|
### Creating Workflows
|
|
1. **Navigate to** Twilio → Workflows
|
|
2. **Create New Workflow**:
|
|
- Name your workflow
|
|
- Select phone number to assign
|
|
- Add steps using the builder
|
|
|
|
3. **Configure Steps**:
|
|
- **Greeting**: Set welcome message and voice
|
|
- **IVR Menu**: Define options and routing
|
|
- **Queue**: Select target queue
|
|
- **Schedule**: Choose business hours schedule
|
|
|
|
### Setting Up Queues
|
|
1. **Create Queue** (Twilio → Queues):
|
|
- Queue Name: Descriptive name
|
|
- Notification Number: SMS alerts for queue activity (optional)
|
|
- Agent Group: Select assigned group
|
|
- Wait Music: URL for hold music
|
|
- Timeout: Maximum wait time
|
|
|
|
2. **Use in Workflows**:
|
|
- Add Queue step to workflow
|
|
- Select queue from dropdown
|
|
- Configure announcement message
|
|
|
|
### Browser Phone Setup
|
|
1. **Create TwiML App** in Twilio Console:
|
|
- Voice Request URL: Your server's TwiML endpoint
|
|
- Copy the Application SID
|
|
|
|
2. **Configure in WordPress**:
|
|
- Go to **Twilio** → **Settings**
|
|
- Enter TwiML App SID
|
|
- Save settings
|
|
|
|
3. **Access Browser Phone**:
|
|
- Navigate to **Twilio** → **Browser Phone**
|
|
- Select caller ID from available numbers
|
|
- Start making/receiving calls
|
|
|
|
### Agent Configuration
|
|
1. **Create Agent Groups** (Twilio → Agent Groups)
|
|
2. **Add Agents** to groups with priorities
|
|
3. **Set Phone Numbers** in user profiles
|
|
4. **Configure Call Mode**: Browser or cell phone
|
|
5. **Train Agents** on SMS commands and browser phone
|
|
|
|
## Voice Configuration
|
|
|
|
### ElevenLabs Integration
|
|
1. **Get API Key** from ElevenLabs dashboard
|
|
2. **Configure in Settings**: Add API key
|
|
3. **Select Voices** in workflow steps:
|
|
- Click "Load Voices" to fetch available options
|
|
- Selected voices are saved with both ID and name
|
|
- Voice names persist across edits without API calls
|
|
|
|
### Audio Options per Step
|
|
- **Say**: Default Twilio text-to-speech
|
|
- **TTS**: ElevenLabs premium voices with persistence
|
|
- **Audio**: Custom MP3 file URLs
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Browser Phone "Client version not supported"
|
|
- **Fixed in latest version**: Upgraded to Voice SDK v2
|
|
- Clear browser cache and reload page
|
|
- Check TwiML App SID is configured
|
|
|
|
#### "Twilio SDK classes not available"
|
|
```bash
|
|
# Reinstall SDK
|
|
./install-twilio-sdk.sh
|
|
# Test installation
|
|
php test-sdk.php
|
|
```
|
|
|
|
#### Calls Not Routing to Queues
|
|
- Verify queue exists and is active
|
|
- Check agent group has members
|
|
- Ensure agents have valid phone numbers
|
|
- Review workflow step configuration
|
|
- Check notification_number field (not phone_number)
|
|
|
|
#### SMS Not Sending from Admin
|
|
- Test with direct PHP script: `php test-twilio-direct.php send`
|
|
- Verify Twilio credentials in settings
|
|
- Check WordPress error logs
|
|
- Ensure number is SMS-capable in Twilio
|
|
|
|
#### Voice Selections Not Saving
|
|
- Voices now save both ID and name automatically
|
|
- No API call needed to display saved voices
|
|
- Click "Load Voices" only to change selection
|
|
- Check browser console for JavaScript errors
|
|
|
|
#### IVR Options Not Working
|
|
- Ensure only active form fields are enabled
|
|
- Check queue selections are properly saved
|
|
- Verify digit mappings in workflow data
|
|
|
|
### Debug Mode
|
|
Enable WordPress debugging in `wp-config.php`:
|
|
```php
|
|
define('WP_DEBUG', true);
|
|
define('WP_DEBUG_LOG', true);
|
|
define('WP_DEBUG_DISPLAY', false);
|
|
```
|
|
|
|
### Testing Tools
|
|
- **Direct SMS Test**: `php test-twilio-direct.php send`
|
|
- **SDK Test**: `php test-sdk.php`
|
|
- **Webhook Simulator**: Use Twilio Console debugger
|
|
- **Call Logs**: Review in WordPress admin
|
|
- **Browser Phone**: Test WebRTC connectivity
|
|
|
|
## Database Structure
|
|
|
|
The plugin creates these tables:
|
|
- `twp_phone_schedules` - Business hours definitions
|
|
- `twp_call_queues` - Queue configurations (uses notification_number)
|
|
- `twp_queued_calls` - Active calls in queues
|
|
- `twp_workflows` - Call flow definitions with voice persistence
|
|
- `twp_call_log` - Complete call history
|
|
- `twp_sms_log` - SMS message tracking
|
|
- `twp_voicemails` - 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
|
|
|
|
## Webhook Endpoints
|
|
|
|
All webhooks are REST API endpoints under `/wp-json/twilio-webhook/v1/`:
|
|
- `/voice` - Main incoming call handler
|
|
- `/sms` - SMS message handler
|
|
- `/ivr-response` - IVR digit collection (fixed in latest)
|
|
- `/queue-wait` - Queue hold experience
|
|
- `/agent-connect` - Agent connection handler
|
|
- `/callback-request` - Callback system
|
|
- `/outbound-agent-with-from` - Outbound calling
|
|
|
|
## Technical Details
|
|
|
|
### Dependencies
|
|
- **Twilio PHP SDK v8.7.0** - Server-side API operations
|
|
- **Twilio Voice SDK v2** - Browser phone WebRTC
|
|
- **WordPress REST API** - Webhook handling
|
|
- **jQuery** - Admin interface interactions
|
|
|
|
### Browser Compatibility
|
|
- **Chrome/Edge**: Full support
|
|
- **Firefox**: Full support
|
|
- **Safari**: Requires HTTPS for WebRTC
|
|
- **Mobile Browsers**: Limited WebRTC support
|
|
|
|
### Security Considerations
|
|
- All webhooks use WordPress nonce verification
|
|
- Phone numbers validated and sanitized
|
|
- SQL queries use prepared statements
|
|
- Sensitive data encrypted in database
|
|
- HTTPS required for production use
|
|
|
|
## Version History
|
|
|
|
### v2.0.0 (Current)
|
|
- Upgraded to Twilio Voice SDK v2 for browser phone
|
|
- Fixed queue notification_number field naming
|
|
- Enhanced voice selection persistence
|
|
- Fixed IVR option saving and loading
|
|
- Improved error handling and logging
|
|
- Added automatic token refresh
|
|
|
|
### v1.3.x
|
|
- Initial release with full call center features
|
|
- Browser phone with Client SDK v1.14
|
|
- Basic workflow builder
|
|
- Queue management system
|
|
|
|
## Support
|
|
|
|
- Check `CLAUDE.md` for detailed technical documentation
|
|
- Review error logs in `/wp-content/debug.log`
|
|
- Monitor Twilio Console for webhook errors
|
|
- Test components individually using provided scripts
|
|
- Report issues with specific error messages and logs
|
|
|
|
## License
|
|
|
|
This plugin integrates with Twilio services and requires a Twilio account. |