wp-plugins/twilio-wp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Add queue timeout voicemail and Amazon SNS SMS provider support

Browse Source 
This update adds two major features:

1. Queue Timeout Voicemail
   - Callers can now leave voicemail when queue timeout is reached
   - Configurable per-queue voicemail prompts with TTS support
   - Automatic transcription and urgent keyword detection
   - Admin setting to choose between voicemail or callback on timeout

2. Amazon SNS SMS Provider
   - Alternative SMS provider to Twilio for sending text messages
   - Useful when Twilio SMS approval is difficult to obtain
   - Provider abstraction layer allows switching between Twilio/SNS
   - Full AWS SNS configuration in admin settings
   - Supports custom sender IDs in compatible countries
   - Lower cost per SMS compared to Twilio

New Files:
- includes/class-twp-voicemail-handler.php - Voicemail recording handler
- includes/interface-twp-sms-provider.php - SMS provider interface
- includes/class-twp-sms-provider-twilio.php - Twilio SMS implementation
- includes/class-twp-sms-provider-sns.php - Amazon SNS implementation
- includes/class-twp-sms-manager.php - SMS provider abstraction manager
- QUEUE_VOICEMAIL_SMS_FEATURES.md - Complete feature documentation

Modified Files:
- includes/class-twp-call-queue.php - Added voicemail option to timeout handler
- includes/class-twp-twilio-api.php - Updated send_sms() to use provider abstraction
- admin/class-twp-admin.php - Added SMS provider and timeout action settings
- composer.json - Added AWS SDK dependency

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jknapp
2025-10-21 11:13:54 -07:00
parent 82b735f5df
commit 4baa8f539a
10 changed files with 1189 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
QUEUE_VOICEMAIL_SMS_FEATURES.md Normal file
View File

@@ -0,0 +1,293 @@
# 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