wp-plugins/twilio-wp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
534d343526abea7a29953ed6aba9d5ab23fedc4c
twilio-wp-plugin/CLAUDE.md
jknapp 304b5de40b progress made
2025-08-11 20:31:48 -07:00

11 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

🚨 CRITICAL: Testing & Deployment Environment

THIS PLUGIN RUNS ON A REMOTE SERVER IN A DOCKER CONTAINER - NOT LOCALLY

  • Production Server Path: /home/shadowdao/public_html/wp-content/plugins/twilio-wp-plugin/
  • Website URL: https://www.streamers.channel/
  • Development Path: /home/jknapp/code/twilio-wp-plugin/
  • Deployment Method: Files synced via rsync from development to Docker container

IMPORTANT:

  • NEVER assume local testing - all tests must work on remote server
  • Direct PHP tests work (php test-twilio-direct.php send)
  • WordPress admin context has issues that need investigation

📞 Standardized Phone Number Variable Names

THESE NAMING CONVENTIONS MUST BE STRICTLY FOLLOWED:

Required Variable Names:

  • incoming_number = Phone number that initiated contact (sent SMS/call TO the system)
  • agent_number = Phone number used to reach a specific agent
  • customer_number = Phone number of customer calling into the system
  • workflow_number = Twilio number assigned to a specific workflow
  • queue_number = Twilio number assigned to a specific queue
  • default_number = Default Twilio number when none specified

BANNED Variable Names (DO NOT USE):

  • ❌ from_number - Ambiguous, could be customer or system
  • ❌ to_number - Ambiguous, could be agent or system
  • ❌ phone_number - Too generic, must specify whose number
  • ❌ $agent_phone - Use $agent_number instead

Test Numbers:

  • Twilio Number: +19516215107
  • Test Agent Number: +19095737372
  • Fake Test Number: +19512345678 (DO NOT SEND SMS TO THIS)

🧪 Testing Procedures

✅ Working: Direct Twilio Test

# SSH into server
cd /home/shadowdao/public_html/wp-content/plugins/twilio-wp-plugin/
php test-twilio-direct.php send

Result: SMS sends successfully via Twilio SDK

❌ Not Working: WordPress Admin SMS

  • Admin pages load and show success messages
  • But SMS doesn't actually send
  • No PHP errors logged
  • No Twilio API calls recorded

Webhook URLs:

  • SMS: https://www.streamers.channel/wp-json/twilio-webhook/v1/sms
  • Voice: https://www.streamers.channel/wp-json/twilio-webhook/v1/voice

Known Issues & Solutions

Issue: SMS not sending from WordPress admin

Symptoms:

  • Direct PHP test works
  • WordPress admin shows success but no SMS sent
  • No errors in logs

Possible Causes:

  1. WordPress execution context differs from CLI
  2. Silent failures in WordPress AJAX/admin context
  3. Plugin initialization issues in admin context

Project Overview

This is a comprehensive WordPress plugin for Twilio voice and SMS integration, featuring:

  • Call Center Functionality: Agent groups, call queues, call distribution
  • Business Hours Management: Schedules for workflow routing
  • Outbound Calling: Click-to-call with proper caller ID
  • SMS Notifications: Agent notifications and callback management
  • Workflow Builder: Visual call flow creation
  • Voicemail System: Recording and transcription
  • Real-time Dashboard: Agent queue management

Plugin Architecture

Core Classes (includes/ directory)

  • TWP_Core: Main plugin initialization and hook registration
  • TWP_Activator: Database table creation and plugin activation
  • TWP_Twilio_API: Official Twilio PHP SDK wrapper (requires SDK v8.7.0)
  • TWP_Webhooks: Handles all Twilio webhook endpoints
  • TWP_Scheduler: Business hours and schedule management
  • TWP_Workflow: Call flow processing and TwiML generation
  • TWP_Call_Queue: Queue management and position tracking
  • TWP_Agent_Groups: Group management for call distribution
  • TWP_Agent_Manager: Agent status and call acceptance
  • TWP_Callback_Manager: Callback requests and processing
  • TWP_Call_Logger: Call logging and statistics

Database Tables

Created by TWP_Activator::create_tables():

  • twp_phone_schedules - Business hours definitions
  • twp_call_queues - Queue configurations
  • twp_queued_calls - Active calls in queues
  • twp_workflows - Call flow definitions
  • twp_call_log - Complete call history
  • twp_sms_log - SMS message tracking
  • twp_voicemails - Voicemail 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

Admin Interface (admin/ directory)

  • TWP_Admin: Complete admin interface with pages for:
    • Dashboard with real-time statistics
    • Business Hours Schedules management
    • Workflow Builder with drag-drop interface
    • Call Queues configuration
    • Phone Numbers management (purchase/configure)
    • Voicemail inbox with playback
    • Call Logs with filtering
    • Agent Groups management
    • Agent Queue dashboard
    • Outbound Calls interface (click-to-call)

Webhook Endpoints

All registered in TWP_Webhooks::register_endpoints():

  • /voice - Main voice webhook for incoming calls
  • /sms - SMS webhook (handles agent "1" responses)
  • /ivr-response - IVR menu selections
  • /queue-wait - Queue hold music and position announcements
  • /ring-group-result - Handle no-answer scenarios and requeuing
  • /agent-connect - Connect SMS-responding agents to calls
  • /callback-* - Callback system webhooks
  • /outbound-agent-with-from - Outbound calling with from number

Key Features Implementation

Agent Group System

  • Simultaneous Ring: All group members called at once
  • Priority Ordering: Members have priority levels
  • SMS Notifications: Automatic alerts when no agents available
  • One-Click Accept: Agents can text "1" to receive calls
  • Real-time Status: Available/busy/offline tracking

Call Queue Management

  • Position Tracking: Callers know their queue position
  • Timeout Handling: Offers callback instead of hanging up
  • Auto-requeue: Failed agent connections return to queue
  • Real-time Dashboard: Agents see waiting calls

Callback System

  • Smart Callbacks: Replace timeout hangups
  • SMS Confirmations: Notify customers of callback requests
  • Automatic Processing: Cron-based callback execution
  • Statistics Tracking: Success rates and timing

Outbound Calling

  • From Number Selection: Choose business line for caller ID
  • Conference Routing: Agent-to-customer connection
  • Call Logging: Track all outbound attempts
  • Proper Caller ID: Target sees business number

WordPress Plugin Conventions

File Structure

twilio-wp-plugin/
├── twilio-wp-plugin.php (main plugin file)
├── includes/ (core functionality)
├── admin/ (admin interface)
├── assets/ (CSS/JS/images)
├── CLAUDE.md (this file)

Class Naming

  • Prefix: TWP_ for all classes
  • Database tables: twp_ prefix
  • Options: twp_ prefix
  • AJAX actions: twp_ prefix

Database Operations

  • Use WordPress $wpdb global for all database operations
  • Always sanitize inputs with sanitize_text_field(), intval(), etc.
  • Use prepared statements with $wpdb->prepare()
  • Call TWP_Activator::ensure_tables_exist() before database operations

AJAX Handling

All AJAX endpoints registered in TWP_Core::define_admin_hooks():

$this->loader->add_action('wp_ajax_twp_action_name', $plugin_admin, 'ajax_action_name');

User Profile Integration

Agent phone numbers stored as user meta:

  • Meta key: twp_phone_number
  • Validation: TWP_Agent_Manager::validate_phone_number()
  • Duplicate checking: TWP_Agent_Manager::is_phone_number_duplicate()

Twilio Integration

Current Implementation (SDK-Only)

  • Official Twilio SDK: Uses twilio/sdk v8.7.0 for all operations
  • TwiML Generation: Uses \Twilio\TwiML\VoiceResponse classes
  • Response Handling: Native Twilio SDK response objects
  • Error Handling: Proper \Twilio\Exceptions\TwilioException handling

Installation Requirements

IMPORTANT: The Twilio PHP SDK v8.7.0 is REQUIRED for this plugin to function.

Installation Methods:

  1. Script Installation (Recommended):

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

  2. Composer Installation:

    composer install

PHP Requirements: PHP 8.0+ required for SDK compatibility

API Response Structure

Current Twilio API responses follow this pattern:

// Success response
[
    'success' => true,
    'data' => [...] // Twilio response data
]

// Error response  
[
    'success' => false,
    'error' => 'Error message',
    'code' => 400
]

// Call SID location
$call_sid = $response['data']['sid']; // NOT $response['call_sid']

TwiML Best Practices

Always include XML declaration:

$twiml = '<?xml version="1.0" encoding="UTF-8"?>';
$twiml .= '<Response>';
$twiml .= '<Say voice="alice">Message</Say>';
$twiml .= '</Response>';

Development Commands

# Install WordPress development dependencies
composer install

# Install JavaScript dependencies  
npm install

# Run PHP CodeSniffer for WordPress coding standards
vendor/bin/phpcs

# Fix PHP coding standards automatically
vendor/bin/phpcbf

# Run PHPUnit tests
vendor/bin/phpunit

# Install Twilio SDK (recommended migration)
composer require twilio/sdk

Testing Approach

Unit Testing

  • Use PHPUnit for PHP code testing
  • Mock WordPress functions using Brain Monkey or WP_Mock
  • Mock Twilio API responses for reliable testing

Integration Testing

  • Test webhook endpoints with Twilio webhook simulator
  • Test complete call flows end-to-end
  • Verify database operations and data integrity

Manual Testing

  • Use Twilio Console to monitor webhook calls
  • Check WordPress error logs for debugging
  • Test with real phone numbers for user experience

Common Issues & Solutions

Database Issues

  • Missing Tables: Call TWP_Activator::ensure_tables_exist()
  • White Admin Modals: Check for PHP errors in workflow loading

Webhook Issues

  • 500 Errors: Check PHP error logs for fatal errors
  • Missing Parameters: Parameters must be in webhook URL, not just POST data
  • TwiML Parse Errors: Always include XML declaration

API Issues

  • Call SID Access: Use $response['data']['sid'] not $response['call_sid']
  • Phone Number Format: Store with + prefix (e.g., "+1234567890")
  • From Number: Must be a verified Twilio number

Agent Management

  • SMS Responses: Agents text "1" to receive calls
  • Phone Validation: Auto-formats US numbers to +1 format
  • Duplicate Prevention: Checks phone numbers across all users

This plugin provides a complete call center solution with professional-grade features suitable for business use.