SKILL.md
Twilio SMS Automation
Comprehensive skill for automating SMS, voice, and verification workflows with Twilio.
Core Workflows
1. SMS Messaging Flow
SMS AUTOMATION FLOW:
┌─────────────────┐
│ Trigger │
│ (Event/API) │
└────────┬────────┘
▼
┌─────────────────┐
│ Message Build │
│ - Template │
│ - Personalize │
└────────┬────────┘
▼
┌─────────────────┐
│ Number Lookup │
│ - Validate │
│ - Format │
└────────┬────────┘
▼
┌─────────────────┐
│ Send │
│ - Twilio API │
│ - Queue │
└────────┬────────┘
▼
┌─────────────────┐
│ Delivery │
│ - Status │
│ - Callback │
└─────────────────┘2. Message Configuration
sms_config:
sender:
phone_number: "+1234567890"
messaging_service_sid: "MG..." # For higher throughput
defaults:
status_callback: "https://api.example.com/sms/status"
validity_period: 14400 # 4 hours
rate_limiting:
messages_per_second: 10
daily_limit_per_recipient: 5
compliance:
opt_out_keywords: ["STOP", "UNSUBSCRIBE", "CANCEL"]
opt_in_required: true
quiet_hours:
start: "21:00"
end: "09:00"
timezone: "America/New_York"Message Templates
Notification Templates
templates:
order_confirmation:
content: |
{{company}}: Your order #{{order_id}} has been confirmed!
Total: ${{total}}
Track: {{tracking_url}}
Reply HELP for assistance.
max_length: 160
shipping_update:
content: |
{{company}}: Your order #{{order_id}} has shipped!
Carrier: {{carrier}}
Tracking: {{tracking_number}}
Delivery: {{estimated_date}}
appointment_reminder:
content: |
Reminder: Your appointment with {{provider}} is tomorrow at {{time}}.
Location: {{address}}
Reply C to confirm or R to reschedule.
two_factor:
content: |
Your {{company}} verification code is: {{code}}
This code expires in 10 minutes.
Don't share this code with anyone.Conversational Templates
two_way_messaging:
welcome:
trigger: opt_in
response: |
Welcome to {{company}} updates!
You'll receive order and shipping notifications.
Reply HELP for commands or STOP to unsubscribe.
help:
trigger: ["HELP", "?", "INFO"]
response: |
{{company}} SMS Commands:
STATUS - Check order status
TRACK - Get tracking info
SUPPORT - Contact support
STOP - Unsubscribe
status_inquiry:
trigger: ["STATUS", "ORDER"]
action: lookup_order
response: |
Order #{{order_id}}: {{status}}
{{#if tracking}}
Tracking: {{tracking_url}}
{{/if}}
unsubscribe:
trigger: ["STOP", "UNSUBSCRIBE"]
action: opt_out
response: |
You've been unsubscribed from {{company}} messages.
Reply START to resubscribe anytime.Verification (2FA)
Verify API Integration
verification_config:
channel: sms # or: call, email, whatsapp
code_settings:
length: 6
expiry_minutes: 10
rate_limits:
max_attempts: 5
lockout_minutes: 30
templates:
sms: "Your {{company}} code is {{code}}"
call: "Your verification code is {{code_spoken}}"Verification Flow
// Start Verification
const verification = await twilio.verify.v2
.services('VA...')
.verifications
.create({
to: '+1234567890',
channel: 'sms',
customCode: '123456', // Optional
locale: 'en'
});
// Check Verification
const check = await twilio.verify.v2
.services('VA...')
.verificationChecks
.create({
to: '+1234567890',
code: '123456'
});
// Result
if (check.status === 'approved') {
// Verification successful
} else {
// Invalid code
}Voice Automation
Outbound Calls
voice_config:
outbound_call:
from: "+1234567890"
twiml_url: "https://api.example.com/voice/script"
status_callback: "https://api.example.com/voice/status"
timeout: 30
record: true
twiml_script: |
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say voice="alice">
Hello {{name}}, this is a reminder about your
appointment tomorrow at {{time}}.
</Say>
<Gather numDigits="1" action="/handle-response">
<Say>Press 1 to confirm, 2 to reschedule.</Say>
</Gather>
</Response>IVR Menu
ivr_menu:
greeting: |
Thank you for calling {{company}}.
For sales, press 1.
For support, press 2.
For billing, press 3.
To speak with an operator, press 0.
routing:
- digit: "1"
action: transfer
destination: "+1987654321"
queue: "sales"
- digit: "2"
action: transfer
destination: "+1876543210"
queue: "support"
- digit: "3"
action: transfer
destination: "+1765432109"
queue: "billing"
- digit: "0"
action: operator
fallback: voicemailBulk Messaging
Campaign Configuration
bulk_campaign:
name: "Holiday Promotion"
audience:
source: segment
filter:
opted_in: true
last_purchase: "> 30_days"
message:
template: holiday_promo
variables:
discount_code: "HOLIDAY20"
schedule:
start_time: "2024-11-25T10:00:00"
timezone: "America/New_York"
batch_size: 100
delay_between_batches: 60 # seconds
tracking:
delivery_report: true
click_tracking: true
conversion_tracking: trueBroadcast Status
CAMPAIGN STATUS: Holiday Promotion
═══════════════════════════════════════
Progress: ████████████████░░░░ 78%
DELIVERY STATS:
Sent: 7,800
Delivered: 7,450 (95.5%)
Failed: 125 (1.6%)
Pending: 225 (2.9%)
ENGAGEMENT:
Clicks: 1,245 (16.7%)
Replies: 89 (1.2%)
Opt-outs: 23 (0.3%)
ERRORS:
Invalid Number: 45
Unsubscribed: 52
Carrier Block: 18
Rate Limited: 10
ESTIMATED COMPLETION: 25 minutesPhone Number Management
Number Lookup
number_lookup:
capabilities:
- carrier_info
- caller_name
- line_type
validation:
- check_format
- verify_active
- detect_landline_vs_mobile
example_response:
phone_number: "+14155551234"
country_code: "US"
carrier:
name: "Verizon"
type: "mobile"
caller_name: "John Doe"
valid: trueNumber Provisioning
number_management:
search_criteria:
country: "US"
area_code: "415"
capabilities: ["SMS", "MMS", "Voice"]
purchase:
phone_number: "+14155559999"
friendly_name: "Marketing Line"
sms_url: "https://api.example.com/sms/incoming"
voice_url: "https://api.example.com/voice/incoming"Analytics Dashboard
SMS ANALYTICS - LAST 30 DAYS
═══════════════════════════════════════
VOLUME:
Sent: 45,230
Delivered: 43,456 (96.1%)
Failed: 1,774 (3.9%)
BY TYPE:
Notifications ████████████░░░░ 62%
Marketing ██████░░░░░░░░░░ 23%
2FA ████░░░░░░░░░░░░ 15%
DELIVERY BY CARRIER:
Verizon ████████████████ 97%
AT&T ███████████████░ 95%
T-Mobile ██████████████░░ 94%
Sprint █████████████░░░ 92%
COST:
Total Spend: $1,245.67
Per Message: $0.0275
Per Delivered: $0.0287
ENGAGEMENT:
Link Clicks: 3,456 (7.9%)
Replies: 892 (2.1%)
Opt-outs: 56 (0.1%)API Examples
Send SMS
// Simple SMS
const message = await twilio.messages.create({
body: 'Hello from Twilio!',
from: '+1234567890',
to: '+0987654321',
statusCallback: 'https://api.example.com/sms/status'
});
// With Messaging Service (recommended for scale)
const message = await twilio.messages.create({
body: 'Order confirmed!',
messagingServiceSid: 'MG...',
to: '+0987654321'
});
// MMS with Media
const mms = await twilio.messages.create({
body: 'Check out this image!',
from: '+1234567890',
to: '+0987654321',
mediaUrl: ['https://example.com/image.jpg']
});Handle Incoming SMS
// Express webhook handler
app.post('/sms/incoming', (req, res) => {
const { From, Body } = req.body;
const twiml = new twilio.twiml.MessagingResponse();
if (Body.toUpperCase() === 'STATUS') {
twiml.message('Your order is on the way!');
} else {
twiml.message('Thanks for your message. We\'ll respond shortly.');
}
res.type('text/xml');
res.send(twiml.toString());
});Best Practices
- Get Consent: Always have opt-in before messaging
- Include Opt-Out: STOP keyword in every message
- Respect Quiet Hours: Don't message late night
- Validate Numbers: Use Lookup API before sending
- Handle Failures: Retry logic for transient errors
- Monitor Delivery: Track delivery rates by carrier
- Stay Compliant: Follow TCPA/CTIA guidelines
- Use Templates: Consistent, tested messages