twilio-wp-plugin/README.md

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

   chmod +x install-twilio-sdk.sh
   ./install-twilio-sdk.sh
   

2. Test the SDK installation:

   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
• Premium Voice Synthesis: ElevenLabs TTS integration for professional-grade voice prompts
• Automatic Queue Creation: Personal and hold queues created automatically for all agents
• Smart Extension System: Unique 3-4 digit extensions auto-assigned for direct dialing

Recent Updates

MAJOR: Complete Call Control System Overhaul (September 2025)

Comprehensive redesign of hold, transfer, and requeue functionality with professional-grade reliability.

🎯 Hold Function - Complete Solution

• Problem Solved: "Queue not found" errors that prevented calls from being put on hold
• Automatic Setup: Personal and hold queues are now created automatically for all agents
• Smart Extensions: Unique 3-4 digit extensions (100-9999) auto-assigned to each agent
• Seamless Experience: Works immediately without any manual queue setup
• Premium Audio: Professional hold messages using ElevenLabs voices (with fallback to Twilio)
• Browser Phone Ready: Handles complex call scenarios from browser phone users

📞 Transfer Function - Professional Grade

• Audio Quality Fixed: Eliminated customers hearing technical webhook URLs during transfers
• Multiple Transfer Types: Extension transfers, queue transfers, browser phone transfers, and external number transfers all work perfectly
• Professional Announcements: "Transferring to extension 101" and "Transferring your call" messages
• Smart Detection: Automatically identifies the correct call to transfer (customer, not agent)
• Outbound Call Support: Transfer functionality now works for both incoming and outgoing calls
• Enhanced Reliability: Comprehensive error handling prevents transfer failures

🔄 Requeue Function - Seamless Operation

• User Experience Fixed: Customers now hear "Placing you back in the queue" instead of technical errors
• Proper Queue Integration: Seamless integration with queue waiting experience and hold music
• Call Preservation: Maintains call history and position tracking when requeuing
• Professional Audio: Uses same premium voice technology as other functions
• Database Consistency: Works with all database schemas and maintains data integrity

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
• 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"

# 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)

Outbound Call Control Issues - RESOLVED

• Customer Disconnections: FIXED - All call control functions now work perfectly for outbound calls
• Hold Not Working: RESOLVED - Automatic queue creation eliminates "queue not found" errors
• Transfer Failures: FIXED - Professional TwiML generation prevents webhook URL errors
• Browser Phone Transfers: ENHANCED - Full support for client: identifier transfers with smart detection
• Requeue Problems: RESOLVED - Customer call leg detection ensures proper queue placement
• Audio Quality: ENHANCED - Premium TTS voices replace technical error messages
• Setup Required: ELIMINATED - Everything works automatically without manual configuration

Customer Number Display Issues - RESOLVED

• "client:agentname" in Voicemails: FIXED - Real customer numbers now display correctly in all interfaces
• Wrong Numbers in Recording Interface: RESOLVED - Enhanced detection shows actual customer phone numbers
• Missing Customer Info: ENHANCED - Smart fallback logic retrieves customer numbers from multiple sources
• Browser Phone Call Issues: PERFECTED - Proper customer identification in all call scenarios
• Admin Interface: IMPROVED - All admin interfaces now consistently show meaningful customer information
• Data Consistency: ENSURED - Customer information remains accurate across all features

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:

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.2.0 (Current - September 2025) - MAJOR RELEASE

• COMPLETE CALL CONTROL REDESIGN: Hold, transfer, and requeue functions completely rebuilt from the ground up
• Automatic Queue Creation: Personal and hold queues created automatically for all users with unique extensions
• Professional Audio Experience: Eliminated technical errors customers could hear during call operations
• ElevenLabs TTS Integration: Premium voice synthesis throughout all call operations with intelligent fallback
• Call Leg Detection: Advanced system for complex outbound call topologies preventing customer disconnections
• Browser Phone Enhancement: Full support for browser phone transfers and complex call scenarios
• User Experience: Seamless call control without any manual setup or configuration required
• Database Consistency: Enhanced schema support with comprehensive fallback mechanisms
• Professional Grade: Enterprise-level reliability and error handling throughout
• Customer Number Detection: Enhanced voicemail and recording interfaces to show real customer numbers
• Extension Management: Automatic 3-4 digit extension assignment for direct dialing capabilities

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
• 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.