diff --git a/CLAUDE.md b/CLAUDE.md index 10da6cc..35aa4e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,7 @@ - **URL**: `https://phone.cloud-hosting.io/` - **Deployment**: rsync to Docker (remote server only, not local) - **SDK**: Twilio PHP SDK v8.7.0 +- **External SDK**: `wp-content/twilio-sdk/` (survives plugin updates) ## Phone Variable Names **Use**: `incoming_number`, `agent_number`, `customer_number`, `workflow_number`, `queue_number`, `default_number` @@ -47,6 +48,25 @@ $api->update_call($customer_call_sid, ['twiml' => $twiml_xml]); - Firefox support added - 1-min agent status auto-revert +## SDK Installation +- **External SDK (Recommended)**: Use `install-twilio-sdk-external.sh` to install SDK to `wp-content/twilio-sdk/` + - Survives WordPress plugin updates + - SDK location defined by `TWP_EXTERNAL_SDK_DIR` constant + - Loading priority: External first, then internal `vendor/` fallback +- **Internal SDK (Alternative)**: Use `install-twilio-sdk.sh` to install to `vendor/` + - Will be deleted when WordPress updates the plugin + - Requires reinstallation after each plugin update +- **SDK Loading**: Plugin checks external location first via autoloader, falls back to internal +- **Post-Update Detection**: Hook on `upgrader_process_complete` checks SDK status and shows warning + +## Browser Phone Configuration +- **Edge Location Setting**: Configurable via Settings → Twilio Edge Location + - Default: `roaming` (auto-select closest edge) + - Options: ashburn, umatilla, dublin, frankfurt, singapore, sydney, tokyo, sao-paulo + - Stored in: `twp_twilio_edge` option + - Used by: Browser phone JavaScript for WebRTC connection + - Critical: Wrong edge causes immediate call failures (e.g., US calls with Sydney edge) + ## Development Notes - **API**: E.164 format (+1XXXXXXXXXX) - **Database**: Use `$wpdb`, prepared statements @@ -61,5 +81,28 @@ $api->update_call($customer_call_sid, ['twiml' => $twiml_xml]); - ElevenLabs TTS with Alice fallback - 68 AJAX actions, 26 REST endpoints +## Recent Technical Changes (v2.8.9) + +### SDK Persistence Between Plugin Updates +- **Problem**: WordPress plugin updates delete entire plugin folder including `vendor/` SDK +- **Solution**: External SDK installation at `wp-content/twilio-sdk/` survives updates +- **Implementation**: + - New constant: `TWP_EXTERNAL_SDK_DIR` points to `wp-content/twilio-sdk/` + - Loading priority in `twp_check_sdk_installation()`: External first, internal fallback + - Classes updated: `TWP_Twilio_API`, `TWP_Webhooks` constructors check external location first + - New script: `install-twilio-sdk-external.sh` automates external installation + - Post-update hook: `twp_check_sdk_after_update()` detects missing SDK after updates + - Admin notices: `twp_sdk_missing_notice()` shows both installation options + - Warning system: `twp_show_sdk_update_warning()` via transient after plugin updates + +### US Calls Failing Fix (Browser Phone) +- **Problem**: Browser phone had hardcoded `edge: 'sydney'`, causing US calls to fail with immediate HANGUP +- **Solution**: Configurable edge location via WordPress settings +- **Implementation**: + - New setting: `twp_twilio_edge` with default value `roaming` + - Settings UI: Dropdown in admin settings with 8 edge options + - Browser phone JS: Uses `get_option('twp_twilio_edge', 'roaming')` instead of hardcoded value + - Edge options: roaming, ashburn, umatilla, dublin, frankfurt, singapore, sydney, tokyo, sao-paulo + --- -*Updated: Sept 2025* \ No newline at end of file +*Updated: Jan 2026* \ No newline at end of file diff --git a/README.md b/README.md index 546493b..375dae6 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,20 @@ This plugin **requires** the Twilio PHP SDK v8.7.0 to function. The plugin will ## Quick Installation -1. **Install the Twilio SDK** (Required): +1. **Install the Twilio SDK** (Required - Recommended Method): + ```bash + chmod +x install-twilio-sdk-external.sh + ./install-twilio-sdk-external.sh + ``` + + This installs the SDK to `wp-content/twilio-sdk/` which **survives WordPress plugin updates**. The plugin will automatically detect and use this external SDK. + + **Alternative Method** (SDK will be deleted during plugin updates): ```bash chmod +x install-twilio-sdk.sh ./install-twilio-sdk.sh ``` + This installs the SDK inside the plugin folder. You'll need to reinstall the SDK after each plugin update. 2. **Test the SDK installation**: ```bash @@ -23,6 +32,7 @@ This plugin **requires** the Twilio PHP SDK v8.7.0 to function. The plugin will - Go to **Twilio** → **Settings** - Enter Account SID and Auth Token - Configure default phone numbers + - Set Twilio Edge Location (for browser phone - see Browser Phone Setup below) 4. **Set up Phone Numbers** in Twilio Console: - Configure webhook URLs for voice and SMS @@ -333,8 +343,20 @@ Comprehensive redesign of hold, transfer, and requeue functionality with profess 2. **Configure in WordPress**: - Go to **Twilio** → **Settings** - Enter TwiML App SID + - **Set Twilio Edge Location**: Select the edge location closest to your users (IMPORTANT) + - **Auto-select closest (Recommended)**: Automatically selects the best edge + - **US East (Ashburn)**: For East Coast USA users + - **US West (Umatilla)**: For West Coast USA users + - **Europe - Ireland (Dublin)**: For European users + - **Europe - Germany (Frankfurt)**: For Central European users + - **Singapore**: For Southeast Asian users + - **Sydney**: For Australian users + - **Tokyo**: For Japanese users + - **Sao Paulo**: For South American users - Save settings + **Note**: Selecting the wrong edge location can cause calls to fail immediately. If you're experiencing browser phone connection issues, verify your edge location is appropriate for your region. + 3. **Access Browser Phone** (Admin Only): - Navigate to **WordPress Admin** → **Twilio** → **Browser Phone** - Select caller ID from available numbers @@ -432,14 +454,34 @@ Access the full browser phone interface at: **WordPress Admin → Twilio → Bro - **Login Required**: Users must be logged in to access browser phone functionality - Check TwiML App SID is configured in WordPress admin settings +#### Browser Phone Calls Failing Immediately +If browser phone calls disconnect immediately or show HANGUP errors: +- **Check Edge Location Setting**: Go to **Twilio** → **Settings** → **Twilio Edge Location** +- **US Users**: Should use "Auto-select closest" (roaming), "US East (Ashburn)", or "US West (Umatilla)" +- **International Users**: Select the edge location closest to your region +- **Problem**: Wrong edge location causes gateway to immediately reject calls +- **Solution**: Change edge location setting and try the call again (no restart needed) + #### "Twilio SDK classes not available" + +**Recommended Solution** (SDK survives plugin updates): ```bash -# Reinstall SDK +# Install SDK to external location +./install-twilio-sdk-external.sh +# Test installation +php test-sdk.php +``` + +**Alternative Solution** (will need reinstall after plugin updates): +```bash +# Install SDK inside plugin folder ./install-twilio-sdk.sh # Test installation php test-sdk.php ``` +**After WordPress Plugin Update**: If you get this error after updating the plugin and used the internal SDK method, you'll need to reinstall the SDK. This won't happen if you use the external SDK method. + #### Calls Not Routing to Queues - Verify queue exists and is active - Check agent group has members @@ -551,7 +593,19 @@ All webhooks are REST API endpoints under `/wp-json/twilio-webhook/v1/`: ## Version History -### v2.3.0 (Current - September 2025) - ENTERPRISE READY +### v2.8.9 (Current - January 2026) - SDK PERSISTENCE & BROWSER PHONE FIXES +- **SDK PERSISTENCE**: External SDK installation option that survives WordPress plugin updates + - New installation script: `install-twilio-sdk-external.sh` installs SDK to `wp-content/twilio-sdk/` + - Automatic detection: Plugin checks external SDK location first, falls back to internal + - Post-update warnings: Notifies if SDK was deleted during plugin update + - Zero downtime: Phone system continues working through plugin updates +- **BROWSER PHONE FIX**: Resolved US calls failing immediately with HANGUP errors + - Made Twilio Edge Location configurable (was hardcoded to Sydney) + - New setting: Twilio Edge Location with 8 options (roaming/auto-select, ashburn, umatilla, dublin, frankfurt, singapore, sydney, tokyo, sao-paulo) + - Default: "roaming" (auto-select closest edge for optimal performance) + - Critical fix: US users can now make calls successfully (were failing with Sydney edge) + +### v2.3.0 (September 2025) - ENTERPRISE READY - **SECURITY ENHANCEMENT**: Removed frontend browser phone interface, moved to admin-only access for enhanced security - **ASSET REDUCTION**: Eliminated 108KB of frontend assets (browser-phone-frontend.js and CSS files) - **SHORTCODE SECURITY**: Browser phone shortcode now provides secure redirect with authentication checks @@ -611,4 +665,4 @@ This plugin integrates with Twilio services and requires a Twilio account. --- -**Enterprise Ready v2.3.0** - Extension transfers, browser phone compatibility, and automatic agent management now production-ready with comprehensive reliability improvements. \ No newline at end of file +**Production Ready v2.8.9** - SDK persistence through plugin updates and configurable edge locations ensure zero-downtime phone operations. \ No newline at end of file diff --git a/admin/class-twp-admin.php b/admin/class-twp-admin.php index 3bad851..3fa0bdb 100644 --- a/admin/class-twp-admin.php +++ b/admin/class-twp-admin.php @@ -340,13 +340,32 @@ class TWP_Admin { TwiML App SID -

TwiML Application SID for Browser Phone (optional). See setup instructions below

- + + + Twilio Edge Location + + + +

Edge location for browser phone calls. Use "Auto-select closest" for best call quality, or select a specific region.

+ + +

Eleven Labs API Settings

@@ -3818,6 +3837,7 @@ class TWP_Admin { register_setting('twilio-wp-settings-group', 'twp_twilio_account_sid'); register_setting('twilio-wp-settings-group', 'twp_twilio_auth_token'); register_setting('twilio-wp-settings-group', 'twp_twiml_app_sid'); + register_setting('twilio-wp-settings-group', 'twp_twilio_edge'); register_setting('twilio-wp-settings-group', 'twp_elevenlabs_api_key'); register_setting('twilio-wp-settings-group', 'twp_elevenlabs_voice_id'); register_setting('twilio-wp-settings-group', 'twp_elevenlabs_model_id'); @@ -7779,7 +7799,7 @@ class TWP_Admin { device = new Twilio.Device(token, { logLevel: 1, // 0 = TRACE, 1 = DEBUG codecPreferences: ['opus', 'pcmu'], - edge: 'sydney', // Or closest edge location + edge: '', enableIceRestart: true, // Important for mobile network switching audioConstraints: audioConstraints, maxCallSignalingTimeoutMs: 30000, // 30 seconds timeout for mobile diff --git a/includes/class-twp-twilio-api.php b/includes/class-twp-twilio-api.php index 5baebfd..9b7f647 100644 --- a/includes/class-twp-twilio-api.php +++ b/includes/class-twp-twilio-api.php @@ -41,13 +41,28 @@ class TWP_Twilio_API { * Initialize Twilio SDK client */ private function init_sdk_client() { - // Check if autoloader exists - $autoloader_path = TWP_PLUGIN_DIR . 'vendor/autoload.php'; - if (!file_exists($autoloader_path)) { - error_log('TWP Plugin: Autoloader not found at: ' . $autoloader_path); - throw new Exception('Twilio SDK not found. Please run: ./install-twilio-sdk.sh'); + // Check for SDK autoloader - external location first (survives plugin updates) + $autoloader_path = null; + + // Priority 1: External SDK location (recommended) + $external_autoloader = TWP_EXTERNAL_SDK_DIR . 'autoload.php'; + if (file_exists($external_autoloader)) { + $autoloader_path = $external_autoloader; } - + + // Priority 2: Internal vendor directory (fallback) + if (!$autoloader_path) { + $internal_autoloader = TWP_PLUGIN_DIR . 'vendor/autoload.php'; + if (file_exists($internal_autoloader)) { + $autoloader_path = $internal_autoloader; + } + } + + if (!$autoloader_path) { + error_log('TWP Plugin: Autoloader not found. Checked: ' . $external_autoloader . ' and ' . TWP_PLUGIN_DIR . 'vendor/autoload.php'); + throw new Exception('Twilio SDK not found. Please run: ./install-twilio-sdk-external.sh'); + } + // Load the autoloader require_once $autoloader_path; diff --git a/includes/class-twp-webhooks.php b/includes/class-twp-webhooks.php index e94b45e..8df0c73 100644 --- a/includes/class-twp-webhooks.php +++ b/includes/class-twp-webhooks.php @@ -9,9 +9,25 @@ class TWP_Webhooks { */ public function __construct() { // Load Twilio SDK if not already loaded + // Check external location first (survives plugin updates), then internal if (!class_exists('\Twilio\Rest\Client')) { - $autoloader_path = plugin_dir_path(dirname(__FILE__)) . 'vendor/autoload.php'; - if (file_exists($autoloader_path)) { + $autoloader_path = null; + + // Priority 1: External SDK location + $external_autoloader = dirname(dirname(plugin_dir_path(dirname(__FILE__)))) . '/twilio-sdk/autoload.php'; + if (file_exists($external_autoloader)) { + $autoloader_path = $external_autoloader; + } + + // Priority 2: Internal vendor directory + if (!$autoloader_path) { + $internal_autoloader = plugin_dir_path(dirname(__FILE__)) . 'vendor/autoload.php'; + if (file_exists($internal_autoloader)) { + $autoloader_path = $internal_autoloader; + } + } + + if ($autoloader_path) { require_once $autoloader_path; } } diff --git a/install-twilio-sdk-external.sh b/install-twilio-sdk-external.sh new file mode 100755 index 0000000..9005fb0 --- /dev/null +++ b/install-twilio-sdk-external.sh @@ -0,0 +1,158 @@ +#!/bin/bash + +# Script to install Twilio PHP SDK to an external location +# This prevents SDK from being deleted when WordPress updates the plugin +# +# Location: wp-content/twilio-sdk/ (outside plugin folder) + +echo "Installing Twilio PHP SDK v8.7.0 to external location..." +echo "This will install the SDK outside the plugin folder to survive plugin updates." + +# Check if we can download files +if ! command -v curl &> /dev/null; then + echo "ERROR: curl is required to download the SDK" + echo "Please install curl and try again" + exit 1 +fi + +if ! command -v tar &> /dev/null; then + echo "ERROR: tar is required to extract the SDK" + echo "Please install tar and try again" + exit 1 +fi + +# Get the script directory (plugin directory) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Calculate wp-content directory (two levels up from plugin) +# Plugin is at: wp-content/plugins/twilio-wp-plugin/ +# We want: wp-content/twilio-sdk/ +WP_CONTENT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")" +SDK_DIR="$WP_CONTENT_DIR/twilio-sdk" + +echo "Plugin directory: $SCRIPT_DIR" +echo "SDK will be installed to: $SDK_DIR" + +# Create SDK directory +mkdir -p "$SDK_DIR/twilio/sdk" + +# Download the latest release (8.7.0) +echo "Downloading Twilio SDK from GitHub..." +TEMP_DIR=$(mktemp -d) +cd "$TEMP_DIR" + +if ! curl -L https://github.com/twilio/twilio-php/archive/refs/tags/8.7.0.tar.gz -o twilio-sdk.tar.gz; then + echo "ERROR: Failed to download Twilio SDK" + echo "Please check your internet connection and try again" + rm -rf "$TEMP_DIR" + exit 1 +fi + +# Extract the archive +echo "Extracting SDK files..." +if ! tar -xzf twilio-sdk.tar.gz; then + echo "ERROR: Failed to extract SDK files" + rm -rf "$TEMP_DIR" + exit 1 +fi + +# Check if the extracted directory exists +if [ ! -d "twilio-php-8.7.0/src" ]; then + echo "ERROR: Extracted SDK directory structure is unexpected" + rm -rf "$TEMP_DIR" + exit 1 +fi + +# Remove existing SDK if it exists +if [ -d "$SDK_DIR/twilio/sdk" ]; then + echo "Removing existing SDK installation..." + rm -rf "$SDK_DIR/twilio/sdk" + mkdir -p "$SDK_DIR/twilio/sdk" +fi + +# Move the entire src directory to be the sdk +echo "Installing SDK files..." +if ! mv twilio-php-8.7.0/src/* "$SDK_DIR/twilio/sdk/"; then + echo "ERROR: Failed to move SDK files" + rm -rf "$TEMP_DIR" + exit 1 +fi + +# Create a comprehensive autoloader +cat > "$SDK_DIR/autoload.php" << 'EOF' +

Twilio WordPress Plugin - SDK Required

The Twilio PHP SDK is required for this plugin to work.

-

To install the SDK, run this command in your plugin directory:

+

Recommended: Install SDK to external location (survives plugin updates):

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

Alternative: Install SDK inside plugin folder:

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

Or install via Composer: composer install

-

Plugin path:

+

Plugin path:

+

External SDK path:

+
+

Twilio WordPress Plugin - SDK Reinstall Required

+

The plugin was updated and the Twilio SDK needs to be reinstalled.

+

To prevent this in the future, install the SDK to the external location:

+ cd && ./install-twilio-sdk-external.sh +

The external SDK at survives plugin updates.

+
+