twilio-wp-plugin/CLAUDE.md

Twilio WordPress Plugin - Quick Reference

Environment

• Production: /home/shadowdao/public_html/wp-content/plugins/twilio-wp-plugin/
• Dev: /home/jknapp/code/twilio-wp-plugin/
• 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
Don't use: from_number, to_number, phone_number, $agent_phone
Test numbers: Twilio +19516215107, Agent +19095737372

Key Classes

• TWP_Twilio_API: Use new TWP_Twilio_API() not singleton
• TWP_Admin: Has find_customer_call_leg() - CRITICAL for call control
• TWP_TTS_Helper: ElevenLabs/Alice fallback, 30-day cache
• TWP_User_Queue_Manager: Auto-creates queues/extensions (100-9999)
• TWP_Webhooks: 26 endpoints at twilio-webhook/v1
• TWP_Activator: Creates 15 DB tables, run ensure_tables_exist() if missing

Database

15 tables with twp_ prefix. Key notes:

• twp_call_queues: User queues (general/personal/hold)
• twp_agent_status: Has auto_busy_at for 1-min auto-revert
• twp_queued_calls: Uses enqueued_at not joined_at

Critical Functions

Call Control (MUST use call leg detection)

// ALWAYS do this for hold/transfer/requeue:
$customer_call_sid = $this->find_customer_call_leg($call_sid, $twilio);
$api->update_call($customer_call_sid, ['twiml' => $twiml_xml]);

Common Fixes

• Recording: Use Twilio.CURRENT for SDK v8
• Queue: Pass waitUrl as option in enqueue()
• TwiML: Use SDK classes, not raw XML

Recent Changes (v2.3.0)

• Browser phone moved to admin-only
• Call control uses find_customer_call_leg() to prevent disconnections
• Auto-creates user queues/extensions when needed
• 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
• AJAX: Verify nonce, return JSON
• Naming: TWP_ for classes, twp_ for tables/options
• Debugging: Look for "TWP Call Leg Detection" in logs

Features

• Agents accept calls via SMS "1"
• User-specific queues with extensions
• Browser phone at admin.php?page=twilio-wp-browser-phone
• 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: Jan 2026