Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems and multi-channel authentication. Critical focus on compliance, rate limits, and error handling. Use when: twilio, send SMS, text message, voice call, phone verification.
Build communication features with Twilio: SMS messaging, voice calls,
WhatsApp Business API, and user verification (2FA). Covers the full
spectrum from simple notifications to complex IVR systems and multi-channel
authentication. Critical focus on compliance, rate limits, and error handling.
Patterns
SMS Sending Pattern
Basic pattern for sending SMS messages with Twilio.
Handles the fundamentals: phone number formatting, message delivery,
and delivery status callbacks.
Key considerations:
Phone numbers must be in E.164 format (+1234567890)
Default rate limit: 80 messages per second (MPS)
Messages over 160 characters are split (and cost more)
Carrier filtering can block messages (especially to US numbers)
When to use: Sending notifications to users,Transactional messages (order confirmations, shipping),Alerts and reminders
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
import os
import re
class TwilioSMS:
"""
SMS sending with proper error handling and validation.
"""
def __init__(self):
self.client = Client(
os.environ["TWILIO_ACCOUNT_SID"],
os.environ["TWILIO_AUTH_TOKEN"]
)
self.from_number = os.environ["TWILIO_PHONE_NUMBER"]
def validate_e164(self, phone: str) -> bool:
"""Validate phone number is in E.164 format."""
pattern = r'^\+[1-9]\d{1,14}$'
return bool(re.match(pattern, phone))
def send_sms(
self,
to: str,
body: str,
status_callback: str = None
) -> dict:
"""
Send an SMS message.
Args:
to: Recipient phone number in E.164 format
body: Message text (160 chars = 1 segment)
status_callback: URL for delivery status webhooks
Returns:
Message SID and status
"""
# Validate phone number format
if not self.validate_e164(to):
return {
"success": False,
"error": "Phone number must be in E.164 format (+1234567890)"
}
# Check message length (warn about segmentation)
segment_count = (len(body) + 159) // 160
if segment_count > 1:
print(f"Warning: Message will be sent as {segment_count} segments")
try:
message = self.client.messages.create(
to=to,
from_=self.from_number,
body=body,
status_callback=status_callback
)
return {
"success": True,
"message_sid": message.sid,
"status": message.status,
"segments": segment_count
}
except TwilioRestException as e:
return self._handle_error(e)
def _handle_error(self, error: TwilioRestException) -> dict:
"""Handle Twilio-specific errors."""
error_handlers = {
21610: "Recipient has opted out. They must reply START.",
21614: "Invalid 'To' phone number format.",
21211: "'From' phone number is not valid.",
30003: "Phone is unreachable (off, airplane mode, no signal).",
30005: "Unknown destination (invalid number or landline).",
30006: "Landline or unreachable carrier.",
30429: "Rate limit exceeded. Implement exponential backoff.",
}
return {
"success": False,
"error_code": error.code,
"error": error_handlers.get(error.code, error.msg),
"details": str(error)
}
async def verify_with_fallback(phone: str, max_attempts: int = 3):
"""Verify with voice fallback if SMS fails."""
for attempt in range(max_attempts):
channel = VerifyChannel.SMS if attempt == 0 else VerifyChannel.CALL
result = verify.send_verification(phone, channel)
if result["success"]:
return result
# If SMS failed, wait and try voice
if channel == VerifyChannel.SMS:
await asyncio.sleep(30)
continue
return {"success": False, "error": "All verification attempts failed"}
Anti_patterns
Storing OTP codes in your database (Twilio handles this)
Not implementing rate limiting on your verify endpoint
Using same-code retries (let Verify generate new codes)
No fallback channel when SMS fails
TwiML IVR Pattern
Build Interactive Voice Response (IVR) systems using TwiML.
TwiML (Twilio Markup Language) is XML that tells Twilio what to do
when receiving calls.
Core TwiML verbs:
<Say>: Text-to-speech
<Play>: Play audio file
<Gather>: Collect keypad/speech input
<Dial>: Connect to another number
<Record>: Record caller's voice
<Redirect>: Move to another TwiML endpoint
Key insight: Twilio makes HTTP request to your webhook, you return
TwiML, Twilio executes it. Stateless, so use URL params or sessions.
When to use: Phone menu systems (press 1 for sales...),Automated customer support,Appointment reminders with confirmation,Voicemail systems
from flask import Flask, request, Response
from twilio.twiml.voice_response import VoiceResponse, Gather
from twilio.request_validator import RequestValidator
import os
app = Flask(name)
def validate_twilio_request(f):
"""Decorator to validate requests are from Twilio."""
def wrapper(*args, **kwargs):
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
# Gather digits with timeout
gather = Gather(
num_digits=1,
action="/voice/menu-selection",
method="POST",
timeout=5
)
gather.say(
"Welcome to Acme Corp. "
"Press 1 for sales. "
"Press 2 for support. "
"Press 3 to leave a message."
)
response.append(gather)
# If no input, repeat
response.redirect("/voice/incoming")
return Response(str(response), mimetype="text/xml")
@app.route("/voice/menu-selection", methods=["POST"])
@validate_twilio_request
def menu_selection():
"""Route based on menu selection."""
response = VoiceResponse()
digit = request.form.get("Digits", "")
if digit == "1":
# Transfer to sales
response.say("Connecting you to sales.")
response.dial(os.environ["SALES_PHONE"])
elif digit == "2":
# Transfer to support
response.say("Connecting you to support.")
response.dial(os.environ["SUPPORT_PHONE"])
elif digit == "3":
# Voicemail
response.say("Please leave a message after the beep.")
response.record(
action="/voice/voicemail-saved",
max_length=120,
transcribe=True,
transcribe_callback="/voice/transcription"
)
else:
response.say("Invalid selection.")
response.redirect("/voice/incoming")
return Response(str(response), mimetype="text/xml")
# TwiML Bin URL or your endpoint
call = client.calls.create(
to=to,
from_=os.environ["TWILIO_PHONE_NUMBER"],
url="https://your-app.com/voice/outbound-message",
status_callback="https://your-app.com/voice/status"
)
return call.sid
if name == "main":
app.run(debug=True)
Anti_patterns
Not validating X-Twilio-Signature (security risk)
Returning non-XML responses to Twilio
Not handling timeout/no-input cases
Hardcoding phone numbers in TwiML
WhatsApp Business API Pattern
Send and receive WhatsApp messages via Twilio API.
Uses the same Twilio Messages API as SMS with minor changes.
Key WhatsApp rules:
24-hour session window: Can only reply within 24 hours of user message
Template messages: Pre-approved templates for outside session window
Opt-in required: Users must explicitly consent to receive messages
Rate limit: 80 MPS default (up to 400 with approval)
Character limits: Non-template 1024 chars, templates ~550 chars
When to use: Customer support with rich media,Order notifications with buttons,Marketing messages (with templates),Interactive flows (booking, surveys)
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
import os
from datetime import datetime, timedelta
from typing import Optional
class TwilioWhatsApp:
"""
WhatsApp Business API via Twilio.
Handles session windows and template messages.
"""
def __init__(self):
self.client = Client(
os.environ["TWILIO_ACCOUNT_SID"],
os.environ["TWILIO_AUTH_TOKEN"]
)
# WhatsApp number format: whatsapp:+14155551234
self.from_number = os.environ["TWILIO_WHATSAPP_NUMBER"]
def send_message(
self,
to: str,
body: str,
media_url: Optional[str] = None
) -> dict:
"""
Send WhatsApp message within 24-hour session.
Args:
to: Recipient number (E.164, without whatsapp: prefix)
body: Message text (max 1024 chars for non-template)
media_url: Optional image/document URL
Returns:
Message result
"""
# Format for WhatsApp
to_whatsapp = f"whatsapp:{to}"
from_whatsapp = f"whatsapp:{self.from_number}"
try:
message_params = {
"to": to_whatsapp,
"from_": from_whatsapp,
"body": body
}
if media_url:
message_params["media_url"] = [media_url]
message = self.client.messages.create(**message_params)
return {
"success": True,
"message_sid": message.sid,
"status": message.status
}
except TwilioRestException as e:
return self._handle_whatsapp_error(e)
def send_template_message(
self,
to: str,
content_sid: str,
content_variables: dict
) -> dict:
"""
Send pre-approved template message.
Use this for messages outside 24-hour window.
Content templates must be approved by WhatsApp first.
Create them in Twilio Console > Content Template Builder.
"""
to_whatsapp = f"whatsapp:{to}"
from_whatsapp = f"whatsapp:{self.from_number}"
try:
message = self.client.messages.create(
to=to_whatsapp,
from_=from_whatsapp,
content_sid=content_sid,
content_variables=content_variables
)
return {
"success": True,
"message_sid": message.sid,
"template": True
}
except TwilioRestException as e:
return self._handle_whatsapp_error(e)
def _handle_whatsapp_error(self, error: TwilioRestException) -> dict:
"""Handle WhatsApp-specific errors."""
error_handlers = {
63016: "Outside 24-hour window. Use template message.",
63018: "Template not approved or doesn't exist.",
63025: "Too many template messages sent to this user.",
63038: "Rate limit exceeded for WhatsApp.",
}
return {
"success": False,
"error_code": error.code,
"error": error_handlers.get(error.code, error.msg)
}
if "order status" in text_lower:
return "Your order #1234 is out for delivery!"
elif "support" in text_lower:
return "A support agent will contact you shortly."
else:
return "Thanks for your message! Reply with 'order status' or 'support'."
Send typing indicator (2025 feature)
def send_typing_indicator(to: str):
"""Let user know you're typing."""
# Requires Senders API setup
pass
def validate_twilio_signature(f):
"""
Validate that request came from Twilio.
CRITICAL: Always use this for webhook endpoints.
"""
@wraps(f)
def wrapper(*args, **kwargs):
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
# Build full URL (including query params)
url = request.url
# Get POST body as dict
params = request.form.to_dict()
# Get signature from header
signature = request.headers.get("X-Twilio-Signature", "")
if not validator.validate(url, params, signature):
logger.warning(f"Invalid Twilio signature from {request.remote_addr}")
abort(403)
return f(*args, **kwargs)
return wrapper
# Handle media attachments
media_urls = []
for i in range(num_media):
media_urls.append(request.form.get(f"MediaUrl{i}"))
# Check for opt-out keywords
if body.strip().upper() in ["STOP", "UNSUBSCRIBE", "CANCEL"]:
handle_opt_out(from_number)
return "", 200
# Check for opt-in keywords
if body.strip().upper() in ["START", "SUBSCRIBE"]:
handle_opt_in(from_number)
return "", 200
# Process message
process_incoming_sms(from_number, body, media_urls)
return "", 200
@app.route("/webhooks/twilio/voice/status", methods=["POST"])
@validate_twilio_signature
def voice_status_callback():
"""Handle call status updates."""
call_sid = request.form.get("CallSid")
status = request.form.get("CallStatus")
duration = request.form.get("CallDuration")
direction = request.form.get("Direction")
messages = [
{"to": "+14155551234", "body": "Hello!"},
{"to": "+14155555678", "body": "Hello!"},
# ... thousands of messages
]
results = await sender.send_bulk(messages)
successful = sum(1 for r in results if r.get("success"))
print(f"Sent {successful}/{len(messages)} messages")
Anti_patterns
Retrying immediately without backoff
No jitter causing thundering herd
Retrying non-rate-limit errors
Exceeding Twilio's MPS limit
Sharp Edges
Sending to Users Who Opted Out (Error 21610)
Severity: HIGH
Situation: Sending SMS to a phone number
Symptoms:
Message fails with error code 21610. Twilio rejects the message.
User never receives the SMS. Same number worked before.
Why this breaks:
The recipient replied "STOP" (or UNSUBSCRIBE, CANCEL, etc.) to a previous
message from your number. Twilio automatically honors opt-outs and blocks
further messages to that number from your account.
This is legally required for US messaging (TCPA, CTIA guidelines).
You cannot override this - the user must reply "START" to opt back in.
Recommended fix:
Track opt-out status in your database
# In your webhook handler
@app.route("/webhooks/sms/incoming", methods=["POST"])
def incoming_sms():
from_number = request.form.get("From")
body = request.form.get("Body", "").strip().upper()
# Standard opt-out keywords
if body in ["STOP", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"]:
mark_user_opted_out(from_number)
return "", 200
# Standard opt-in keywords
if body in ["START", "SUBSCRIBE", "YES", "UNSTOP"]:
mark_user_opted_in(from_number)
return "", 200
# Process other messages...
# Before sending
def send_sms_safe(to: str, body: str):
if is_user_opted_out(to):
return {"success": False, "error": "User has opted out"}
try:
return send_sms(to, body)
except TwilioRestException as e:
if e.code == 21610:
# Update database - they opted out via carrier
mark_user_opted_out(to)
raise
Include opt-out instructions
Add "Reply STOP to unsubscribe" to marketing messages.
Phone Unreachable But Valid (Error 30003)
Severity: MEDIUM
Situation: Sending SMS to a mobile number
Symptoms:
Message fails with error 30003. Number was valid and worked before.
Intermittent - sometimes works, sometimes fails.
Why this breaks:
Error 30003 means "Unreachable destination handset." The phone exists but
can't receive messages right now. Common causes:
Phone powered off
Airplane mode
Out of signal range
Carrier network issues
Phone storage full
Unlike 30006 (permanent unreachable), 30003 is usually temporary.
Recommended fix:
Implement retry logic for transient failures
TRANSIENT_ERRORS = [30003, 30008, 30009] # Retriable errors
async def send_with_retry(to: str, body: str, max_retries: int = 3):
for attempt in range(max_retries):
result = send_sms(to, body)
if result["success"]:
return result
if result.get("error_code") not in TRANSIENT_ERRORS:
# Don't retry permanent failures
return result
# Exponential backoff: 5min, 15min, 45min
delay = 300 * (3 ** attempt)
await asyncio.sleep(delay)
return {"success": False, "error": "Max retries exceeded"}
Symptoms:
Messages show as "sent" but never "delivered." No error from Twilio.
Users say they never received the message. Pattern in specific carriers
or message content.
Why this breaks:
US carriers (Verizon, AT&T, T-Mobile) aggressively filter SMS for spam.
Your message might be blocked if:
Contains URLs (especially short URLs or unknown domains)
Looks like phishing (urgent, account, verify, click now)
High volume from same number
Not using registered A2P 10DLC
Low sender reputation
Carriers don't tell Twilio why messages are filtered - they just
silently drop them.
Recommended fix:
Register for A2P 10DLC (US requirement)
1. Go to Twilio Console > Messaging > Trust Hub
2. Register your business brand
3. Create a messaging campaign (describes use case)
4. Wait for approval (can take days)
5. Associate phone numbers with campaign
Message content best practices
def sanitize_message(text: str) -> str:
"""Make message less likely to be filtered."""
# Avoid URL shorteners - use full domain
# Avoid spam trigger words
# Keep it conversational, not promotional
# Example: Instead of this
bad = "URGENT: Verify your account now! Click: bit.ly/abc"
# Do this
good = "Hi! Your order #1234 is ready. Questions? Reply here."
return text
# Use toll-free or short code for high volume
# 10DLC is for <10K msg/day
# Toll-free: up to 10K msg/day
# Short code: 100K+ msg/day
Monitor delivery rates
def track_delivery_rate():
sent = get_messages_with_status("sent")
delivered = get_messages_with_status("delivered")
rate = len(delivered) / len(sent) * 100
if rate < 95:
alert_team(f"Delivery rate dropped to {rate}%")
Not Validating Webhook Signatures
Severity: CRITICAL
Situation: Receiving Twilio webhook callbacks
Symptoms:
Attackers send fake webhooks to your endpoint. Fraudulent transactions
processed. Spoofed incoming messages trigger actions.
Why this breaks:
Twilio signs all webhook requests with X-Twilio-Signature header.
If you don't validate this, anyone who knows your webhook URL can
send fake requests pretending to be Twilio.
This can lead to:
Fake message delivery confirmations
Spoofed incoming messages
Fraudulent verification approvals
Recommended fix:
ALWAYS validate the signature
from twilio.request_validator import RequestValidator
from flask import Flask, request, abort
from functools import wraps
import os
def require_twilio_signature(f):
"""Decorator to validate Twilio webhook requests."""
@wraps(f)
def wrapper(*args, **kwargs):
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
# Full URL including query string
url = request.url
# POST body as dict
params = request.form.to_dict()
# Signature header
signature = request.headers.get("X-Twilio-Signature", "")
if not validator.validate(url, params, signature):
abort(403)
return f(*args, **kwargs)
return wrapper
@app.route("/webhooks/twilio", methods=["POST"])
@require_twilio_signature # ALWAYS use this
def twilio_webhook():
# Safe to process
pass
Common validation gotchas
# URL must match EXACTLY what Twilio called
# If behind proxy, you might need:
url = request.headers.get("X-Forwarded-Proto", "http") + "://" + \
request.headers.get("X-Forwarded-Host", request.host) + \
request.path
# If using ngrok, URL changes each restart
# Use consistent URL in production
1. Twilio Console > Content Template Builder
2. Create template with {{1}} placeholders
3. Submit for WhatsApp approval (takes 24-48 hours)
4. Use content_sid to send
Exposed Account SID or Auth Token
Severity: CRITICAL
Situation: Deploying Twilio integration
Symptoms:
Unauthorized charges on Twilio account. Messages sent you didn't send.
Phone numbers purchased without authorization.
Why this breaks:
If attackers get your Account SID + Auth Token, they have FULL access
to your Twilio account. They can:
Send messages (charging your account)
Buy phone numbers
Access call recordings
Modify your configuration
Common exposure points:
Hardcoded in source code (pushed to GitHub)
In client-side JavaScript
In Docker images
In logs
Recommended fix:
Never hardcode credentials
# BAD - never do this
client = Client("AC1234...", "abc123...")
# GOOD - environment variables
client = Client(
os.environ["TWILIO_ACCOUNT_SID"],
os.environ["TWILIO_AUTH_TOKEN"]
)
# GOOD - secrets manager
from aws_secretsmanager import get_secret
creds = get_secret("twilio-credentials")
client = Client(creds["sid"], creds["token"])
Use API Key instead of Auth Token
# Auth Token has full account access
# API Keys can be scoped and revoked
# Create API Key in Twilio Console
client = Client(
os.environ["TWILIO_API_KEY_SID"],
os.environ["TWILIO_API_KEY_SECRET"],
os.environ["TWILIO_ACCOUNT_SID"]
)
# If compromised, revoke just that key
Rotate tokens immediately if exposed
1. Twilio Console > Account > API credentials
2. Rotate Auth Token
3. Update all deployments with new token
4. Review account activity for unauthorized use
Verify Rate Limit Exceeded (Error 60203)
Severity: MEDIUM
Situation: Sending verification codes
Symptoms:
Verification request fails with error 60203.
"Max send attempts reached for this phone number."
Why this breaks:
Twilio Verify has built-in rate limits to prevent abuse:
5 verification attempts per phone number per service per 10 minutes
Helps prevent SMS pumping fraud
Protects against brute-force attacks
If users legitimately need more attempts, you may have UX issues.
Recommended fix:
Implement application-level rate limiting too
from datetime import datetime, timedelta
import redis
class VerifyRateLimiter:
def __init__(self, redis_client):
self.redis = redis_client
# Stricter than Twilio's limit
self.max_attempts = 3
self.window_minutes = 10
def can_request(self, phone: str) -> bool:
key = f"verify_rate:{phone}"
attempts = self.redis.get(key)
if attempts and int(attempts) >= self.max_attempts:
return False
return True
def record_attempt(self, phone: str):
key = f"verify_rate:{phone}"
pipe = self.redis.pipeline()
pipe.incr(key)
pipe.expire(key, self.window_minutes * 60)
pipe.execute()
def get_wait_time(self, phone: str) -> int:
"""Return seconds until user can request again."""
key = f"verify_rate:{phone}"
ttl = self.redis.ttl(key)
return max(0, ttl)
# Usage
limiter = VerifyRateLimiter(redis_client)
@app.route("/verify/send", methods=["POST"])
def send_verification():
phone = request.json["phone"]
if not limiter.can_request(phone):
wait = limiter.get_wait_time(phone)
return {
"error": f"Too many attempts. Try again in {wait} seconds."
}, 429
result = twilio_verify.send_verification(phone)
if result["success"]:
limiter.record_attempt(phone)
return result
Provide clear user feedback
# Show remaining attempts
# Show countdown timer
# Offer alternative (voice call, email)
Validation Checks
Hardcoded Twilio Credentials
Severity: ERROR
Twilio credentials must never be hardcoded
Message: Hardcoded Twilio SID detected. Use environment variables.
Auth Token in Source Code
Severity: ERROR
Auth tokens should be in environment variables
Message: Hardcoded auth token. Use os.environ['TWILIO_AUTH_TOKEN'].
Webhook Without Signature Validation
Severity: ERROR
Twilio webhooks must validate X-Twilio-Signature
Message: Webhook without signature validation. Add RequestValidator check.
Twilio Credentials in Client-Side Code
Severity: ERROR
Never expose Twilio credentials to browsers
Message: Twilio credentials exposed client-side. Only use server-side.
No E.164 Phone Number Validation
Severity: WARNING
Phone numbers should be validated before sending
Message: Sending to phone without E.164 validation.
Hardcoded Phone Numbers
Severity: WARNING
Phone numbers should come from config or database
Message: Hardcoded phone number. Use config or environment variable.
No Twilio Exception Handling
Severity: WARNING
Twilio calls should handle TwilioRestException
Message: Twilio API call without error handling. Catch TwilioRestException.
Not Handling Specific Error Codes
Severity: INFO
Handle common Twilio error codes specifically
Message: Consider handling specific error codes (21610, 30003, etc.).
No Opt-Out Keyword Handling
Severity: WARNING
SMS systems must handle STOP/UNSUBSCRIBE keywords
Message: No opt-out handling. Check for STOP/UNSUBSCRIBE keywords.
Not Checking Opt-Out Before Sending
Severity: WARNING
Check if user has opted out before sending SMS
Message: Consider checking opt-out status before sending.
Collaboration
Delegation Triggers
user needs AI voice assistant -> voice-agents (Twilio provides telephony, voice-agents skill for AI conversation)
user needs Slack notifications -> slack-bot-builder (Integrate SMS alerts with Slack notifications)
user needs full auth system -> auth-specialist (Twilio Verify is one component of broader auth)
user needs workflow automation -> workflow-automation (Trigger SMS/calls from automated workflows)
