wp-plugins/twilio-wp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2cb9b9472d6fa34629326d3d31c9a601b0823527
twilio-wp-plugin/README.md
jknapp 4c353096fe Add mobile-friendly browser phone shortcode for frontend use 
- Created TWP_Shortcodes class with [twp_browser_phone] shortcode
- Mobile-first responsive CSS design with touch-friendly interface
- Frontend JavaScript integration with Twilio Voice SDK v2
- Permission checks for logged-in users with twp_access_browser_phone capability
- Haptic feedback and dark mode support
- Configurable shortcode parameters (title, show_title, compact)
- Updated plugin version to 2.1.0 in main file
- Added comprehensive documentation to README.md

Features:
- Visual dialpad with DTMF support
- Real-time connection status indicators
- Call timer and queue management
- Auto-scaling for mobile devices (320px+)
- Optimized for both desktop and mobile use

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-13 13:45:25 -07:00

448 lines
17 KiB
Markdown
Raw Blame History

# 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 or frontend
- **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
- **Mobile-Friendly**: Responsive design optimized for smartphones and tablets
- **Shortcode Support**: Embed browser phone on any page with `[twp_browser_phone]`
### 🕒 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
### 🔔 Discord & Slack Notifications
- **Real-time Alerts**: Instant notifications to Discord channels and Slack workspaces
- **Multiple Event Types**: Incoming calls, queue timeouts, and missed calls
- **Rich Formatting**: Structured messages with caller info, queue details, and timestamps
- **Webhook Integration**: Simple configuration with webhook URLs
- **Configurable Options**: Enable/disable specific notification types
- **Automatic Monitoring**: Background checks for queue timeout situations
### 📊 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 per workflow
- **Agent Phone Management**: Store and validate agent phone numbers
- **Duplicate Prevention**: Ensures unique phone numbers per agent
- **Enhanced Notifications**: Discord and Slack integration for real-time alerts
## 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
### Multiple Phone Numbers Support
- **Workflow Enhancement**: Workflows can now be assigned to multiple phone numbers
- **Junction Table**: New `twp_workflow_phones` table for many-to-many relationships
- **Backward Compatibility**: Existing single-number workflows continue to work
- **Validation Fixes**: Proper validation for multiple phone number selections
### Discord & Slack Notifications
- **Real-time Integration**: Instant notifications to Discord channels and Slack workspaces
- **Event Monitoring**: Automated tracking of incoming calls, queue timeouts, and missed calls
- **Rich Message Format**: Structured notifications with caller details, queue info, and timestamps
- **Configurable Settings**: Toggle notification types and set custom webhook URLs
- **Background Processing**: Cron-based monitoring for queue timeout alerts
## 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 (multiple numbers per workflow supported)
### Creating Workflows
1. **Navigate to** Twilio → Workflows
2. **Create New Workflow**:
- Name your workflow
- Select phone numbers to assign (multiple selection supported)
- 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
### Discord & Slack Setup
1. **Discord Configuration**:
- Create a webhook URL in your Discord server settings
- Navigate to **Twilio** → **Settings** → **Notifications**
- Paste Discord webhook URL
- Enable desired notification types
2. **Slack Configuration**:
- Create a webhook URL in your Slack workspace
- Navigate to **Twilio** → **Settings** → **Notifications**
- Paste Slack webhook URL
- Configure notification preferences
3. **Notification Types**:
- **Incoming Calls**: Alert when calls enter queues
- **Queue Timeouts**: Alert when calls wait too long (configurable threshold)
- **Missed Calls**: Alert when calls are abandoned or timeout
## Frontend Browser Phone
### Shortcode Usage
The browser phone can be embedded on any WordPress page using the `[twp_browser_phone]` shortcode. This is perfect for creating dedicated agent pages or customer service portals.
**Basic Usage:**
```
[twp_browser_phone]
```
**With Options:**
```
[twp_browser_phone title="Customer Service Phone" show_title="true" compact="false"]
```
### Shortcode Parameters
- **title**: Custom title for the phone widget (default: "Browser Phone")
- **show_title**: Display the title above the phone (default: "true")
- **compact**: Use compact layout for smaller spaces (default: "false")
### Permission Requirements
- Users must be **logged in** to access the browser phone
- Users need the **`twp_access_browser_phone`** capability or **`manage_options`**
- Phone Agent role users have access by default
### Mobile Optimization
- **Responsive Design**: Adapts to all screen sizes
- **Touch-Friendly**: Large buttons optimized for mobile devices
- **Haptic Feedback**: Vibration on button press (where supported)
- **Auto-Zoom Prevention**: Proper viewport handling for mobile browsers
- **Dark Mode Support**: Automatically adapts to user's system preference
## 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_workflow_phones` - Junction table for multiple phone numbers per workflow
- `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.1.0 (Current)
- **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
- **Notification System**: Configurable webhook-based notifications
- **Background Processing**: Cron jobs for timeout monitoring
- **Database Enhancements**: New junction table for phone number relationships
### v2.0.0
- 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.
Reference in New Issue View Git Blame Copy Permalink