twilio-communications

name	twilio-communications
description	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.
risk	unknown
source	vibeship-spawner-skills (Apache 2.0)
date_added	"2026-02-27T00:00:00.000Z"

Twilio Communications

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 ([phone])
• 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 ([phone])"
        }

    # 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)
    }

Usage

sms = TwilioSMS() result = sms.send_sms( to="[phone]", body="Your order #1234 has shipped!", status_callback="https://your-app.com/webhooks/twilio/status" )

Anti_patterns

• Not validating E.164 format before sending
• Hardcoding Twilio credentials in code
• Ignoring delivery status callbacks
• Not handling the opted-out (21610) error

Twilio Verify Pattern (2FA/OTP)

Use Twilio Verify for phone number verification and 2FA. Handles code generation, delivery, rate limiting, and fraud prevention.

Key benefits over DIY OTP:

• Twilio manages code generation and expiration
• Built-in fraud prevention (saved customers $82M+ blocking 747M attempts)
• Handles rate limiting automatically
• Multi-channel: SMS, Voice, Email, Push, WhatsApp

Google found SMS 2FA blocks "100% of automated bots, 96% of bulk phishing attacks, and 76% of targeted attacks."

When to use: User phone number verification at signup,Two-factor authentication (2FA),Password reset verification,High-value transaction confirmation

from twilio.rest import Client from twilio.base.exceptions import TwilioRestException import os from enum import Enum from typing import Optional

class VerifyChannel(Enum): SMS = "sms" CALL = "call" EMAIL = "email" WHATSAPP = "whatsapp"

class TwilioVerify: """ Phone verification with Twilio Verify. Never store OTP codes - Twilio handles it. """

def __init__(self, verify_service_sid: str = None):
    self.client = Client(
        os.environ["TWILIO_ACCOUNT_SID"],
        os.environ["TWILIO_AUTH_TOKEN"]
    )
    # Create a Verify Service in Twilio Console first
    self.service_sid = verify_service_sid or os.environ["TWILIO_VERIFY_SID"]

def send_verification(
    self,
    to: str,
    channel: VerifyChannel = VerifyChannel.SMS,
    locale: str = "en"
) -> dict:
    """
    Send verification code to phone/email.

    Args:
        to: Phone number (E.164) or email
        channel: SMS, call, email, or whatsapp
        locale: Language code for message

    Returns:
        Verification status
    """
    try:
        verification = self.client.verify \
            .v2 \
            .services(self.service_sid) \
            .verifications \
            .create(
                to=to,
                channel=channel.value,
                locale=locale
            )

        return {
            "success": True,
            "status": verification.status,  # "pending"
            "channel": channel.value,
            "valid": verification.valid
        }

    except TwilioRestException as e:
        return self._handle_verify_error(e)

def check_verification(self, to: str, code: str) -> dict:
    """
    Check if verification code is correct.

    Args:
        to: Phone number or email that received code
        code: The code entered by user

    Returns:
        Verification result
    """
    try:
        check = self.client.verify \
            .v2 \
            .services(self.service_sid) \
            .verification_checks \
            .create(
                to=to,
                code=code
            )

        return {
            "success": True,
            "valid": check.status == "approved",
            "status": check.status  # "approved" or "pending"
        }

    except TwilioRestException as e:
        # Code was wrong or expired
        return {
            "success": False,
            "valid": False,
            "error": str(e)
        }

def _handle_verify_error(self, error: TwilioRestException) -> dict:
    """Handle Verify-specific errors."""
    error_handlers = {
        60200: "Invalid phone number format",
        60203: "Max send attempts reached for this number",
        60205: "Service not found - check VERIFY_SID",
        60223: "Failed to create verification - carrier rejected",
    }

    return {
        "success": False,
        "error_code": error.code,
        "error": error_handlers.get(error.code, error.msg)
    }

Usage Example - Signup Flow

verify = TwilioVerify()

Step 1: User enters phone number

result = verify.send_verification("[phone]", VerifyChannel.SMS) if result["success"]: print("Code sent! Check your phone.")

Step 2: User enters the code they received

code = "123456" # From user input check = verify.check_verification("[phone]", code)

if check["valid"]: print("Phone verified! Create account.") else: print("Invalid code. Try again.")

Best Practice: Offer voice fallback

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:

• : Text-to-speech
• : Play audio file
• : Collect keypad/speech input
• : Connect to another number
• : Record caller's voice
• : 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"])

    # Get request details
    url = request.url
    params = request.form.to_dict()
    signature = request.headers.get("X-Twilio-Signature", "")

    if not validator.validate(url, params, signature):
        return "Invalid request", 403

    return f(*args, **kwargs)
wrapper.__name__ = f.__name__
return wrapper

@app.route("/voice/incoming", methods=["POST"]) @validate_twilio_request def incoming_call(): """Handle incoming call with IVR menu.""" response = VoiceResponse()

# 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")

@app.route("/voice/voicemail-saved", methods=["POST"]) @validate_twilio_request def voicemail_saved(): """Handle saved voicemail.""" response = VoiceResponse()

recording_url = request.form.get("RecordingUrl")
recording_sid = request.form.get("RecordingSid")

# Save to database, notify team, etc.
print(f"Voicemail saved: {recording_url}")

response.say("Thank you. Goodbye.")
response.hangup()

return Response(str(response), mimetype="text/xml")

@app.route("/voice/transcription", methods=["POST"]) @validate_twilio_request def transcription_callback(): """Handle voicemail transcription.""" transcription = request.form.get("TranscriptionText") recording_sid = request.form.get("RecordingSid")

# Save transcription, send to Slack, etc.
print(f"Transcription: {transcription}")

return "", 200

Outbound call example

from twilio.rest import Client

def make_outbound_call(to: str, message: str): """Make outbound call with custom TwiML.""" client = Client( os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"] )

# 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:[phone]
    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)
    }

Flask webhook for incoming WhatsApp messages

from flask import Flask, request

app = Flask(name)

@app.route("/webhooks/whatsapp", methods=["POST"]) def whatsapp_webhook(): """Handle incoming WhatsApp messages.""" from_number = request.form.get("From", "").replace("whatsapp:", "") body = request.form.get("Body", "") media_url = request.form.get("MediaUrl0") # First attachment

# Track session start (24-hour window begins now)
session_start = datetime.now()
session_expires = session_start + timedelta(hours=24)

# Store in database for session tracking
# user_sessions[from_number] = session_expires

# Process message and respond
response = process_whatsapp_message(from_number, body, media_url)

# Reply within session
whatsapp = TwilioWhatsApp()
whatsapp.send_message(from_number, response)

return "", 200

def process_whatsapp_message(phone: str, text: str, media: str) -> str: """Process incoming message and generate response.""" text_lower = text.lower()

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

Anti_patterns

• Sending non-template messages outside 24-hour window
• Not tracking session windows per user
• Exceeding 1024 char limit for session messages
• Not handling template rejection errors

Webhook Handler Pattern

Handle Twilio webhooks for delivery status, incoming messages, and call events. Critical: always validate X-Twilio-Signature.

Twilio sends webhooks for:

• Message status updates (queued → sent → delivered/failed)
• Incoming SMS/WhatsApp messages
• Call events (initiated, ringing, answered, completed)
• Recording/transcription ready

When to use: Tracking message delivery status,Receiving incoming messages,Call analytics and logging,Voicemail transcription processing

from flask import Flask, request, abort from twilio.request_validator import RequestValidator from functools import wraps import os import logging

app = Flask(name) logger = logging.getLogger(name)

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

@app.route("/webhooks/twilio/sms/status", methods=["POST"]) @validate_twilio_signature def sms_status_callback(): """ Handle SMS delivery status updates.

Status progression: queued → sending → sent → delivered
Or: queued → sending → undelivered/failed
"""
message_sid = request.form.get("MessageSid")
status = request.form.get("MessageStatus")
error_code = request.form.get("ErrorCode")
error_message = request.form.get("ErrorMessage")

logger.info(f"SMS {message_sid}: {status}")

if status == "delivered":
    # Message successfully delivered
    update_message_status(message_sid, "delivered")

elif status == "undelivered":
    # Carrier rejected or other failure
    logger.error(f"SMS failed: {error_code} - {error_message}")
    handle_failed_message(message_sid, error_code, error_message)

elif status == "failed":
    # Twilio couldn't send
    logger.error(f"SMS send failed: {error_code}")
    handle_failed_message(message_sid, error_code, error_message)

return "", 200

@app.route("/webhooks/twilio/sms/incoming", methods=["POST"]) @validate_twilio_signature def incoming_sms(): """ Handle incoming SMS messages. """ from_number = request.form.get("From") to_number = request.form.get("To") body = request.form.get("Body") num_media = int(request.form.get("NumMedia", 0))

# 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")

# Call statuses: initiated, ringing, in-progress, completed, busy, no-answer, canceled, failed

logger.info(f"Call {call_sid}: {status} ({duration}s)")

if status == "completed":
    # Call ended normally
    log_call_completion(call_sid, duration)

elif status in ["busy", "no-answer", "canceled", "failed"]:
    # Call didn't connect
    handle_failed_call(call_sid, status)

return "", 200

Helper functions

def update_message_status(message_sid: str, status: str): """Update message status in database.""" pass

def handle_failed_message(message_sid: str, error_code: str, error_msg: str): """Handle failed message delivery.""" # Notify team, retry logic, etc. pass

def handle_opt_out(phone: str): """Handle user opting out of messages.""" # Mark user as opted out in database # IMPORTANT: Must respect this! pass

def handle_opt_in(phone: str): """Handle user opting back in.""" pass

def process_incoming_sms(from_phone: str, body: str, media: list): """Process incoming SMS message.""" pass

def log_call_completion(call_sid: str, duration: str): """Log completed call.""" pass

def handle_failed_call(call_sid: str, status: str): """Handle call that didn't connect.""" pass

Anti_patterns

• Not validating X-Twilio-Signature
• Exposing webhook URLs without authentication
• Not handling opt-out keywords (STOP)
• Blocking webhook response (should be fast)

Rate Limit and Retry Pattern

Handle Twilio rate limits and implement proper retry logic.

Default limits:

• SMS: 80 messages per second (MPS)
• Voice: Varies by number type and region
• API calls: 100 requests per second

Error codes:

• 20429: Voice API rate limit
• 30429: Messaging API rate limit

When to use: High-volume messaging applications,Bulk SMS campaigns,Automated calling systems

import time import random from functools import wraps from twilio.base.exceptions import TwilioRestException import logging

logger = logging.getLogger(name)

def exponential_backoff_retry( max_retries: int = 5, base_delay: float = 1.0, max_delay: float = 60.0, rate_limit_codes: list = [20429, 30429] ): """ Decorator for exponential backoff retry on rate limits.

Uses jitter to prevent thundering herd.
"""
def decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        last_exception = None

        for attempt in range(max_retries + 1):
            try:
                return func(*args, **kwargs)

            except TwilioRestException as e:
                last_exception = e

                # Only retry on rate limit errors
                if e.code not in rate_limit_codes:
                    raise

                if attempt == max_retries:
                    logger.error(f"Max retries exceeded: {e}")
                    raise

                # Calculate delay with jitter
                delay = min(
                    base_delay * (2 ** attempt) + random.uniform(0, 1),
                    max_delay
                )

                logger.warning(
                    f"Rate limited (attempt {attempt + 1}/{max_retries}). "
                    f"Retrying in {delay:.1f}s"
                )
                time.sleep(delay)

        raise last_exception

    return wrapper
return decorator

Usage

from twilio.rest import Client

client = Client(account_sid, auth_token)

@exponential_backoff_retry(max_retries=5) def send_sms(to: str, body: str): return client.messages.create( to=to, from_=from_number, body=body )

Bulk sending with rate limiting

import asyncio from asyncio import Semaphore

class RateLimitedSender: """ Send messages with built-in rate limiting. Stays under Twilio's 80 MPS limit. """

def __init__(self, client, from_number: str, mps: int = 50):
    self.client = client
    self.from_number = from_number
    self.mps = mps
    self.semaphore = Semaphore(mps)

async def send_bulk(self, messages: list[dict]) -> list[dict]:
    """
    Send messages with rate limiting.

    Args:
        messages: List of {"to": "+1...", "body": "..."}

    Returns:
        Results for each message
    """
    tasks = [
        self._send_with_limit(msg["to"], msg["body"])
        for msg in messages
    ]

    return await asyncio.gather(*tasks, return_exceptions=True)

async def _send_with_limit(self, to: str, body: str):
    """Send single message with semaphore-based rate limit."""
    async with self.semaphore:
        try:
            # Use sync client in thread pool
            loop = asyncio.get_event_loop()
            result = await loop.run_in_executor(
                None,
                lambda: self.client.messages.create(
                    to=to,
                    from_=self.from_number,
                    body=body
                )
            )
            return {"success": True, "sid": result.sid, "to": to}

        except TwilioRestException as e:
            return {"success": False, "error": str(e), "to": to}

        finally:
            # Delay to maintain rate limit
            await asyncio.sleep(1 / self.mps)

Usage

async def send_campaign(): sender = RateLimitedSender(client, from_number, mps=50)

messages = [
    {"to": "[phone]", "body": "Hello!"},
    {"to": "[phone]", "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"}

Provide fallback channel

async def notify_user(user, message):
    # Try SMS first
    result = await send_sms(user.phone, message)

    if result.get("error_code") == 30003:
        # Phone unreachable - try email
        await send_email(user.email, message)
        return {"channel": "email", "status": "sent"}

    return {"channel": "sms", "status": result["status"]}

Messages Blocked by Carrier Filtering

Severity: HIGH

Situation: Sending SMS to US phone numbers

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

WhatsApp Message Outside 24-Hour Window (Error 63016)

Severity: HIGH

Situation: Sending WhatsApp message to a user

Symptoms: Message fails with error 63016. "Message is outside the allowed window." Template messages work, but regular messages fail.

Why this breaks: WhatsApp has strict rules about unsolicited messages:

• Users must message you first
• You can only reply within 24 hours of their last message
• After 24 hours, you must use pre-approved template messages

This prevents spam and maintains WhatsApp's trust as a platform.

Recommended fix:

Track session windows per user

from datetime import datetime, timedelta

class WhatsAppSession:
    def __init__(self, redis_client):
        self.redis = redis_client
        self.window_hours = 24

    def start_session(self, phone: str):
        """Start/refresh 24-hour session on incoming message."""
        key = f"wa_session:{phone}"
        expires = datetime.now() + timedelta(hours=self.window_hours)
        self.redis.set(key, expires.isoformat(), ex=self.window_hours * 3600)

    def can_send_freeform(self, phone: str) -> bool:
        """Check if we can send non-template message."""
        key = f"wa_session:{phone}"
        expires_str = self.redis.get(key)

        if not expires_str:
            return False

        expires = datetime.fromisoformat(expires_str)
        return datetime.now() < expires

    def send_message(self, phone: str, body: str, template_sid: str = None):
        """Send message, using template if outside window."""
        if self.can_send_freeform(phone):
            return send_whatsapp_message(phone, body)
        elif template_sid:
            return send_whatsapp_template(phone, template_sid)
        else:
            return {
                "success": False,
                "error": "Outside session window, template required"
            }

Incoming message webhook

@app.route("/webhooks/whatsapp", methods=["POST"])
def whatsapp_incoming():
    from_phone = request.form.get("From").replace("whatsapp:", "")

    # Start/refresh session
    session.start_session(from_phone)

    # Process message...

Create approved templates for common messages

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)
• user needs high-volume messaging -> devops (Scale webhooks, monitor delivery rates)

When to Use

• User mentions or implies: twilio
• User mentions or implies: send SMS
• User mentions or implies: text message
• User mentions or implies: voice call
• User mentions or implies: phone verification
• User mentions or implies: 2FA SMS
• User mentions or implies: WhatsApp API
• User mentions or implies: programmable messaging
• User mentions or implies: IVR system
• User mentions or implies: TwiML
• User mentions or implies: phone number verification

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.