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:

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

Installation

1. Install AWS SDK (if not already installed):

   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:

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

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

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