twilio-wp-plugin/QUEUE_VOICEMAIL_SMS_FEATURES.md

# Queue Timeout Voicemail & Amazon SNS SMS Features

## Overview

This update adds two major features to the Twilio WordPress Plugin:

1. **Queue Timeout Voicemail**: Automatically prompt callers to leave a voicemail when they reach the queue timeout limit
2. **Amazon SNS SMS Provider**: Use Amazon SNS as an alternative SMS provider to Twilio

## Feature 1: Queue Timeout Voicemail

### What it does

When a caller waits in a queue beyond the configured timeout period, instead of just disconnecting or offering a callback, the system can now automatically prompt them to leave a voicemail message.

### Benefits

- **Better Caller Experience**: Callers can leave a message instead of being disconnected
- **No Missed Opportunities**: Capture important messages even when agents are unavailable
- **Automatic Transcription**: Voicemails are automatically transcribed
- **Urgent Keyword Detection**: System detects urgent keywords in transcriptions and sends priority notifications

### Configuration

1. Go to **WordPress Admin → Twilio WP → Settings**
2. Find the **SMS Provider Settings** section
3. Under **Queue Timeout Action**, select:
   - **Take Voicemail** (recommended) - Prompts caller to leave a message
   - **Offer Callback** (original behavior) - Offers to call them back

### How it works

1. Caller waits in queue beyond timeout limit
2. System plays customizable voicemail prompt (can be set per-queue)
3. Caller records voicemail (max 5 minutes)
4. Recording is automatically transcribed
5. If urgent keywords detected, priority notifications sent
6. Voicemail appears in admin panel under **Voicemails & Recordings**

### Customization

Each queue can have a custom voicemail prompt. The default prompt is:

> "We're sorry, but all our agents are currently unavailable. Please leave a message after the tone, and we'll get back to you as soon as possible."

### Files Added

- `includes/class-twp-voicemail-handler.php` - Handles voicemail recording and processing

### Files Modified

- `includes/class-twp-call-queue.php` - Updated `handle_timeout()` method

---

## Feature 2: Amazon SNS SMS Provider

### What it does

Provides an alternative to Twilio for sending SMS messages using Amazon SNS (Simple Notification Service). This is particularly useful if you're having difficulty getting Twilio SMS messaging approved.

### Benefits

- **Alternative to Twilio SMS**: No need for Twilio SMS approval
- **AWS Integration**: Use your existing AWS infrastructure
- **Cost Effective**: Pay-as-you-go pricing with AWS
- **Global Reach**: Support for international SMS
- **Sender ID Support**: Use custom sender names in supported countries

### Prerequisites

1. **AWS Account**: You need an AWS account
2. **IAM User**: Create an IAM user with SNS permissions
3. **AWS SDK**: Installed automatically via Composer

#### Required IAM Permissions

Your AWS IAM user needs the following permissions:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:Publish",
                "sns:SetSMSAttributes",
                "sns:GetSMSAttributes"
            ],
            "Resource": "*"
        }
    ]
}
```

### Installation

1. **Install AWS SDK** (if not already installed):
   ```bash
   cd /home/jknapp/code/twilio-wp-plugin
   composer require aws/aws-sdk-php
   ```

2. **Configure AWS Credentials**:
   - Go to **WordPress Admin → Twilio WP → Settings**
   - Find **SMS Provider Settings** section
   - Select **Amazon SNS** from the SMS Provider dropdown
   - Enter your AWS credentials:
     - AWS Access Key ID
     - AWS Secret Access Key
     - AWS Region (e.g., us-east-1)
     - SMS Sender ID (optional, 3-11 alphanumeric characters)

3. **Test the Configuration**:
   ```php
   // Test via WordPress admin or run this code
   require_once 'includes/class-twp-sms-manager.php';
   $result = TWP_SMS_Manager::send_test_sms('+1234567890');
   ```

### Configuration Options

#### SMS Provider Selection

Navigate to **Settings → SMS Provider Settings**:

- **Twilio** (default): Uses your existing Twilio setup
- **Amazon SNS**: Uses AWS Simple Notification Service

#### AWS SNS Settings

When Amazon SNS is selected, configure:

1. **AWS Access Key ID**: Your IAM access key
2. **AWS Secret Access Key**: Your IAM secret key
3. **AWS Region**: Choose your preferred AWS region
4. **SMS Sender ID** (Optional): Alphanumeric sender name (3-11 chars)
   - Supported in: UK, EU, India, and other countries
   - Not supported in: USA, Canada
   - Leave blank to use AWS's default number

### Usage

The SMS provider is transparent to the rest of the plugin. All existing SMS functionality will automatically use the selected provider:

- Agent notifications
- Queue alerts
- Urgent voicemail notifications
- Workflow SMS steps

### Switching Providers

You can switch between Twilio and Amazon SNS at any time:

1. Go to **Settings → SMS Provider Settings**
2. Change the **SMS Provider** dropdown
3. Click **Save Changes**

All SMS messages will immediately use the new provider.

### Cost Comparison

#### Twilio SMS Pricing (approximate)
- US/Canada: $0.0079 per SMS
- Requires SMS verification/approval
- Monthly fees may apply

#### Amazon SNS SMS Pricing (approximate)
- US: $0.00645 per SMS
- No approval required for transactional messages
- Pay only for what you use
- [AWS SNS Pricing Details](https://aws.amazon.com/sns/sms-pricing/)

### Files Added

- `includes/interface-twp-sms-provider.php` - SMS provider interface
- `includes/class-twp-sms-provider-twilio.php` - Twilio SMS provider implementation
- `includes/class-twp-sms-provider-sns.php` - Amazon SNS SMS provider implementation
- `includes/class-twp-sms-manager.php` - SMS provider manager

### Files Modified

- `includes/class-twp-twilio-api.php` - Updated `send_sms()` to use SMS manager
- `admin/class-twp-admin.php` - Added SMS provider settings UI
- `composer.json` - Added AWS SDK dependency

---

## Troubleshooting

### Queue Timeout Voicemail

**Issue**: Voicemail not recording
- Check that queue has a timeout value set (not 0)
- Verify Twilio webhooks are accessible
- Check WordPress error logs for details

**Issue**: No transcription
- Transcription is automatic from Twilio
- Can take a few minutes to process
- Check voicemail record in database

### Amazon SNS SMS

**Issue**: SMS not sending
- Verify AWS credentials are correct
- Check IAM permissions include `sns:Publish`
- Ensure phone number is in E.164 format (+1XXXXXXXXXX)
- Check AWS region is correct

**Issue**: "AWS SDK not found"
- Run: `composer require aws/aws-sdk-php`
- Ensure composer autoload is working
- Check that `vendor/` directory exists

**Issue**: Sender ID not showing
- Sender ID only works in certain countries
- US/Canada don't support alphanumeric sender IDs
- Use default AWS number instead

### Testing

#### Test Voicemail
1. Call your Twilio number
2. Wait for queue timeout (or set timeout to 10 seconds for testing)
3. Leave a voicemail when prompted
4. Check admin panel → Voicemails & Recordings

#### Test SMS Provider
```php
// Add to a test script or run via admin
require_once 'includes/class-twp-sms-manager.php';

// Test current provider
$validation = TWP_SMS_Manager::validate_current_provider();
print_r($validation);

// Send test message
$result = TWP_SMS_Manager::send_test_sms('+1XXXXXXXXXX');
print_r($result);
```

---

## Migration Notes

### Upgrading

Both features are backward compatible:

- **Queue Timeout**: Defaults to voicemail, can be changed to callback
- **SMS Provider**: Defaults to Twilio, no action required

### Database Changes

No database schema changes required. Uses existing:
- `twp_voicemails` table
- WordPress options table for settings

### Rollback

To revert to original behavior:

1. **Queue Timeout**: Change setting to "Offer Callback"
2. **SMS Provider**: Change setting to "Twilio"

---

## Support

For issues or questions:

1. Check error logs: `/wp-content/debug.log`
2. Review Twilio webhook logs
3. Check AWS CloudWatch logs (for SNS)
4. Contact plugin support

---

## Version History

**v2.4.0** - October 2025
- Added queue timeout voicemail feature
- Added Amazon SNS SMS provider support
- Added SMS provider abstraction layer
- Updated admin settings UI

---

## Credits

Developed for Twilio WordPress Plugin