opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/twilio-communications/SKILL.md

@@ -16,1556 +16,9 @@ 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
+## Detailed Guide
 
-### 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)
-        }
-
-# Usage
-sms = TwilioSMS()
-result = sms.send_sms(
-    to="+14155551234",
-    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("+14155551234", 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("+14155551234", 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:
-- <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"])
-
-        # 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:+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)
-        }
-
-# 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": "+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
-
-```python
-# 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
-
-```python
-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
-
-```python
-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
-
-```python
-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
-
-```python
-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
-
-```python
-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
-
-```python
-# 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
-
-```python
-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
-
-```python
-@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
-
-```python
-# 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
-
-```python
-# 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
-
-```python
-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
-
-```python
-# 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)
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 
 ## When to Use
 - User mentions or implies: twilio