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

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

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

---
*Updated: Sept 2025*