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)
```php
// 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*