twilio-sms

Purpose

Enable OpenClaw to implement and operate Twilio Programmable Messaging (SMS/MMS) in production:

• Send SMS/MMS reliably (Messaging Services, geo-matching, sticky sender, media constraints).
• Receive inbound messages via webhooks and respond with TwiML.
• Track delivery lifecycle via status callbacks (queued/sent/delivered/undelivered/failed).
• Implement opt-out/STOP compliance and keyword workflows.
• Operate A2P 10DLC (US long code) and toll-free verification constraints.
• Debug and harden: signature validation, retries, idempotency, rate limits, carrier errors.

This skill is for engineers building messaging pipelines, customer notifications, 2-way support, and compliance-sensitive messaging.

---

Prerequisites

Accounts & Twilio Console setup

• Twilio account with Programmable Messaging enabled.
• At least one of:
  • Messaging Service (recommended) with sender pool (long codes / toll-free / short code).
  • A dedicated Phone Number capable of SMS/MMS.
• For US A2P 10DLC:
  • Brand + Campaign registration completed in Twilio Console (Messaging → Regulatory Compliance / A2P 10DLC).
• For toll-free:
  • Toll-free verification submitted/approved if sending high volume to US/CA.

Runtime versions (tested)

• Node.js 20.11.1 (LTS) + npm 10.2.4
• Python 3.11.7
• Twilio SDKs:
  • twilio (Node) 4.23.0
  • twilio (Python) 9.4.1
• Web framework examples:
  • Express 4.18.3
  • FastAPI 0.109.2 + Uvicorn 0.27.1
• Optional tooling:
  • Twilio CLI 5.16.0
  • ngrok 3.13.1 (local webhook tunneling)
  • Docker 25.0.3 + Compose v2 2.24.6

Credentials & auth

You need:

• TWILIO_ACCOUNT_SID (starts with AC...)
• TWILIO_AUTH_TOKEN
• One of:
  • TWILIO_MESSAGING_SERVICE_SID (starts with MG...) preferred
  • TWILIO_FROM_NUMBER (E.164, e.g. +14155552671)

Store secrets in a secret manager (AWS Secrets Manager / GCP Secret Manager / Vault). For local dev, .env is acceptable.

Network & webhook requirements

• Public HTTPS endpoint for inbound and status callbacks.
• Must accept application/x-www-form-urlencoded (Twilio default) and/or JSON depending on endpoint.
• Validate Twilio signatures (X-Twilio-Signature) on inbound webhooks.

---

Core Concepts

Programmable Messaging objects

• Message: a single outbound or inbound SMS/MMS. Identified by MessageSid (SM...).
• Messaging Service: abstraction over senders; supports:
  • sender pool
  • geo-matching
  • sticky sender
  • smart encoding
  • status callback configuration
• Status Callback: webhook invoked as message state changes.
• Inbound Webhook: webhook invoked when Twilio receives an inbound message to your number/service.

Delivery lifecycle (practical)

Typical MessageStatus values you will see:

• queued → sending → sent → delivered
• Failure paths:
  • undelivered (carrier rejected / unreachable)
  • failed (Twilio could not send; configuration/auth issues)

Treat sent as “handed to carrier”, not “delivered”.

TwiML for Messaging

Inbound SMS/MMS webhooks can respond with TwiML:

<Response>
  <Message>Thanks. We received your message.</Message>
</Response>

Use TwiML for synchronous replies; use REST API for async workflows.

Opt-out compliance

• Twilio automatically handles standard opt-out keywords (e.g., STOP, UNSUBSCRIBE).
• When a user opts out, Twilio blocks further messages from that sender/service to that recipient until they opt back in (START).
• Your app should:
  • treat opt-out as a first-class state
  • avoid retry storms on blocked recipients
  • log and suppress sends to opted-out numbers

A2P 10DLC / short codes / toll-free

• US A2P 10DLC: required for application-to-person messaging over US long codes at scale. Unregistered traffic may be filtered or blocked.
• Short codes: high throughput, expensive, long provisioning.
• Toll-free: good for US/CA; verification improves deliverability and throughput.

Webhook retries and idempotency

Twilio retries webhooks on non-2xx responses. Your webhook handlers must be:

• idempotent (dedupe by MessageSid / SmsSid)
• fast (respond quickly; enqueue work)
• resilient (return 2xx once accepted)

---

Installation & Setup

Official Python SDK — Messaging

Repository: https://github.com/twilio/twilio-python
PyPI: pip install twilio · Supported: Python 3.7–3.13

from twilio.rest import Client
client = Client()  # TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN from env

# Send SMS
msg = client.messages.create(
    body="Hello from Python!",
    from_="+15017250604",
    to="+15558675309"
)
print(msg.sid)

# List recent messages
for m in client.messages.list(limit=20):
    print(m.body, m.status)

Source: twilio/twilio-python — messages

Ubuntu 22.04 (x86_64 / ARM64)

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg jq

Node.js 20 via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v   # v20.11.1 (or later 20.x)
npm -v    # 10.2.4 (or later)

Python 3.11:

sudo apt-get install -y python3.11 python3.11-venv python3-pip
python3.11 --version

Twilio CLI 5.16.0:

npm install -g twilio-cli@5.16.0
twilio --version

ngrok 3.13.1 (optional):

curl -fsSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/ngrok.gpg
echo "deb [signed-by=/usr/share/keyrings/ngrok.gpg] https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt-get update && sudo apt-get install -y ngrok
ngrok version

Fedora 39 (x86_64 / ARM64)

sudo dnf install -y curl jq nodejs python3.11 python3.11-pip
node -v
python3.11 --version

Twilio CLI:

sudo npm install -g twilio-cli@5.16.0
twilio --version

macOS (Intel + Apple Silicon)

Homebrew:

brew update
brew install node@20 python@3.11 jq

Ensure PATH:

echo 'export PATH="/opt/homebrew/opt/node@20/bin:/opt/homebrew/opt/python@3.11/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
node -v
python3.11 --version

Twilio CLI:

npm install -g twilio-cli@5.16.0
twilio --version

ngrok:

brew install ngrok/ngrok/ngrok
ngrok version

Docker (all platforms)

docker --version
docker compose version

Twilio CLI authentication

Interactive login:

twilio login

Or set env vars (CI):

export TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
export TWILIO_AUTH_TOKEN="your_auth_token"

Verify:

twilio api:core:accounts:fetch --sid "$TWILIO_ACCOUNT_SID"

Local webhook tunneling (ngrok)

ngrok http 3000
# note the https forwarding URL, e.g. https://f3a1-203-0-113-10.ngrok-free.app

Configure Twilio inbound webhook to:

• https://.../twilio/inbound
• Status callback to:
  • https://.../twilio/status

---

Key Capabilities

Send SMS/MMS (REST API)

• Use Messaging Service (messagingServiceSid) for production.
• Use statusCallback for delivery receipts.
• Use provideFeedback=true for carrier feedback (where supported).

Node (SMS):

import twilio from "twilio";

const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const msg = await client.messages.create({
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
  to: "+14155550123",
  body: "Build 742 deployed. Reply STOP to opt out.",
  statusCallback: "https://api.example.com/twilio/status",
  provideFeedback: true,
});

console.log(msg.sid, msg.status);

Python (MMS):

from twilio.rest import Client
import os

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

msg = client.messages.create(
    messaging_service_sid=os.environ["TWILIO_MESSAGING_SERVICE_SID"],
    to="+14155550123",
    body="Here is the incident screenshot.",
    media_url=["https://cdn.example.com/incidents/INC-2048.png"],
    status_callback="https://api.example.com/twilio/status",
)
print(msg.sid, msg.status)

Production constraints for MMS:

• Media must be publicly reachable via HTTPS.
• Content-type and size limits vary by carrier; keep images small (< 500KB) when possible.
• Use signed URLs with sufficient TTL (>= 1 hour) if private.

---

Receive inbound SMS/MMS (webhook)

Inbound webhook receives form-encoded fields like:

• From, To, Body
• MessageSid (or SmsSid legacy)
• NumMedia, MediaUrl0, MediaContentType0, ...

Express handler with signature validation:

import express from "express";
import twilio from "twilio";

const app = express();

// Twilio sends application/x-www-form-urlencoded by default
app.use(express.urlencoded({ extended: false }));

app.post("/twilio/inbound", (req, res) => {
  const signature = req.header("X-Twilio-Signature") || "";
  const url = "https://api.example.com/twilio/inbound"; // must match public URL exactly

  const isValid = twilio.validateRequest(
    process.env.TWILIO_AUTH_TOKEN,
    signature,
    url,
    req.body
  );

  if (!isValid) {
    return res.status(403).send("Invalid signature");
  }

  const from = req.body.From;
  const body = (req.body.Body || "").trim();

  // Fast path: respond immediately; enqueue work elsewhere
  const twiml = new twilio.twiml.MessagingResponse();
  if (body.toUpperCase() === "HELP") {
    twiml.message("Support: https://status.example.com. Reply STOP to opt out.");
  } else {
    twiml.message("Received. Ticket created.");
  }

  res.type("text/xml").send(twiml.toString());
});

app.listen(3000);

FastAPI handler:

from fastapi import FastAPI, Request, Response
from twilio.request_validator import RequestValidator
from twilio.twiml.messaging_response import MessagingResponse
import os

app = FastAPI()
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])

@app.post("/twilio/inbound")
async def inbound(request: Request):
    form = await request.form()
    signature = request.headers.get("X-Twilio-Signature", "")
    url = "https://api.example.com/twilio/inbound"

    if not validator.validate(url, dict(form), signature):
        return Response("Invalid signature", status_code=403)

    body = (form.get("Body") or "").strip()
    resp = MessagingResponse()
    resp.message("Received.")
    return Response(str(resp), media_type="text/xml")

---

Delivery receipts (status callback webhook)

Status callback receives:

• MessageSid
• MessageStatus (queued, sent, delivered, undelivered, failed)
• To, From
• ErrorCode (e.g., 30003)
• ErrorMessage (sometimes present)

Express:

app.post("/twilio/status", express.urlencoded({ extended: false }), async (req, res) => {
  // Validate signature same as inbound; use exact public URL
  const messageSid = req.body.MessageSid;
  const status = req.body.MessageStatus;
  const errorCode = req.body.ErrorCode ? Number(req.body.ErrorCode) : null;

  // Idempotency: upsert by messageSid + status
  // Example: write to DB with unique constraint (messageSid, status)
  console.log({ messageSid, status, errorCode });

  res.status(204).send();
});

Operational guidance:

• Treat callbacks as at-least-once delivery.
• Persist state transitions; do not assume ordering.
• Use callbacks to:
  • mark notifications delivered
  • trigger fallback channels (email/push) on undelivered/failed
  • compute deliverability metrics by carrier/region

---

Opt-out / STOP handling

Twilio blocks messages to opted-out recipients automatically. Your system should:

• Detect opt-out keywords on inbound messages and update your own contact preferences.
• Suppress sends to opted-out recipients to avoid repeated 21610 errors.

Inbound keyword handling:

const normalized = body.trim().toUpperCase();
const isStop = ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"].includes(normalized);
const isStart = ["START", "YES", "UNSTOP"].includes(normalized);

if (isStop) {
  // mark user opted out in your DB
}
if (isStart) {
  // mark user opted in
}

When sending, pre-check your DB opt-out state. If you still hit Twilio block, handle error code 21610.

---

Messaging Services: sender pools, geo-matching, sticky sender

Use a Messaging Service to:

• avoid hardcoding From
• rotate senders safely
• enable geo-matching (local presence)
• enable sticky sender (consistent From per recipient)

Create a service (CLI):

twilio api:messaging:v1:services:create \
  --friendly-name "prod-notifications" \
  --status-callback "https://api.example.com/twilio/status"

Add a phone number to the service:

twilio api:messaging:v1:services:phone-numbers:create \
  --service-sid YOUR_MG_SID \
  --phone-number-sid PN0123456789abcdef0123456789abcdef

Enable sticky sender / geo-match (via API; CLI coverage varies by version):

twilio api:messaging:v1:services:update \
  --sid YOUR_MG_SID \
  --sticky-sender true \
  --area-code-geomatch true

---

A2P 10DLC operational checks (US)

What to enforce in code:

• If sending to US numbers (+1...) from US long codes:
  • ensure the sender is associated with an approved A2P campaign
  • ensure message content matches campaign use case (avoid content drift)
• Monitor filtering:
  • rising 30003/30005 and undelivered rates
  • carrier violations and spam flags

Twilio Console is the source of truth for registration state; in CI/CD, treat campaign IDs and service SIDs as config.

---

Short codes and toll-free

• Short code: high throughput, best deliverability; long lead time.
• Toll-free: good for US/CA; verification required for scale.

Implementation is identical at API level; difference is provisioning and compliance.

---

Webhook security: signature validation and URL correctness

Signature validation is brittle if:

• you validate against the wrong URL (must match the public URL Twilio used)
• you have proxies altering scheme/host
• you parse body differently than Twilio expects

If behind a reverse proxy (ALB/NGINX), reconstruct the public URL using forwarded headers carefully, or hardcode the known public URL per route.

---

Command Reference

Twilio CLI (5.16.0)

Authentication / environment

twilio login
twilio profiles:list
twilio profiles:use <profile>

Set env vars for a single command:

TWILIO_ACCOUNT_SID=AC... TWILIO_AUTH_TOKEN=... twilio api:core:accounts:fetch --sid AC...

Send a message (CLI)

Twilio CLI has a twilio api:core:messages:create command (core API). Common flags:

twilio api:core:messages:create \
  --to "+14155550123" \
  --from "+14155552671" \
  --body "Deploy complete." \
  --status-callback "https://api.example.com/twilio/status" \
  --provide-feedback true \
  --max-price 0.015 \
  --application-sid AP0123456789abcdef0123456789abcdef

Notes on flags:

• --to (required): destination E.164.
• --from: sender number (E.164). Prefer Messaging Service instead.
• --messaging-service-sid MG...: use service; mutually exclusive with --from.
• --body: SMS text.
• --media-url: repeatable; MMS media URL(s).
• --status-callback: webhook for status updates.
• --provide-feedback: request carrier feedback (not always available).
• --max-price: cap price (USD) for message; may cause failures if too low.
• --application-sid: for TwiML app association (rare for Messaging).

MMS example:

twilio api:core:messages:create \
  --to "+14155550123" \
  --messaging-service-sid YOUR_MG_SID \
  --body "Photo" \
  --media-url "https://cdn.example.com/a.png" \
  --media-url "https://cdn.example.com/b.jpg"

Fetch message:

twilio api:core:messages:fetch --sid SM0123456789abcdef0123456789abcdef

List messages (filters vary; core ones):

twilio api:core:messages:list --limit 50
twilio api:core:messages:list --to "+14155550123" --limit 20
twilio api:core:messages:list --from "+14155552671" --limit 20

Delete message record (rare; mostly for cleanup/testing):

twilio api:core:messages:remove --sid SM0123456789abcdef0123456789abcdef

Messaging Services

Create:

twilio api:messaging:v1:services:create \
  --friendly-name "prod-notifications" \
  --status-callback "https://api.example.com/twilio/status"

Update:

twilio api:messaging:v1:services:update \
  --sid YOUR_MG_SID \
  --friendly-name "prod-notifications" \
  --status-callback "https://api.example.com/twilio/status" \
  --inbound-request-url "https://api.example.com/twilio/inbound" \
  --inbound-method POST

List:

twilio api:messaging:v1:services:list --limit 50

Fetch:

twilio api:messaging:v1:services:fetch --sid YOUR_MG_SID

Phone numbers attached to a service:

twilio api:messaging:v1:services:phone-numbers:list \
  --service-sid YOUR_MG_SID \
  --limit 50

Attach a number:

twilio api:messaging:v1:services:phone-numbers:create \
  --service-sid YOUR_MG_SID \
  --phone-number-sid PN0123456789abcdef0123456789abcdef

Remove a number from service:

twilio api:messaging:v1:services:phone-numbers:remove \
  --service-sid YOUR_MG_SID \
  --sid PN0123456789abcdef0123456789abcdef

Incoming phone numbers (to find PN SIDs)

List numbers:

twilio api:core:incoming-phone-numbers:list --limit 50

Fetch:

twilio api:core:incoming-phone-numbers:fetch --sid PN0123456789abcdef0123456789abcdef

Update webhook on a number (if not using Messaging Service inbound URL):

twilio api:core:incoming-phone-numbers:update \
  --sid PN0123456789abcdef0123456789abcdef \
  --sms-url "https://api.example.com/twilio/inbound" \
  --sms-method POST \
  --sms-fallback-url "https://api.example.com/twilio/fallback" \
  --sms-fallback-method POST \
  --status-callback "https://api.example.com/twilio/status"

---

Configuration Reference

Environment variables

Recommended variables:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_MESSAGING_SERVICE_SID (preferred)
• TWILIO_FROM_NUMBER (only if not using service)
• TWILIO_STATUS_CALLBACK_URL
• TWILIO_INBOUND_WEBHOOK_PUBLIC_URL (for signature validation)

Node.js .env

Path: /srv/app/.env (Linux) or project root for local dev.

TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
TWILIO_AUTH_TOKEN=0123456789abcdef0123456789abcdef
TWILIO_MESSAGING_SERVICE_SID=YOUR_MG_SID
TWILIO_STATUS_CALLBACK_URL=https://api.example.com/twilio/status
TWILIO_INBOUND_WEBHOOK_PUBLIC_URL=https://api.example.com/twilio/inbound

Load with dotenv:

npm install dotenv@16.4.5

import "dotenv/config";

systemd unit (production)

Path: /etc/systemd/system/messaging-api.service

[Unit]
Description=Messaging API
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=messaging
Group=messaging
WorkingDirectory=/srv/messaging-api
EnvironmentFile=/etc/messaging-api/env
ExecStart=/usr/bin/node /srv/messaging-api/dist/server.js
Restart=on-failure
RestartSec=2
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/messaging-api /var/log/messaging-api
AmbientCapabilities=
CapabilityBoundingSet=

[Install]
WantedBy=multi-user.target

Secrets file path: /etc/messaging-api/env (chmod 600)

sudo install -m 600 -o root -g root /dev/null /etc/messaging-api/env

Example /etc/messaging-api/env:

TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
TWILIO_AUTH_TOKEN=0123456789abcdef0123456789abcdef
TWILIO_MESSAGING_SERVICE_SID=YOUR_MG_SID
TWILIO_STATUS_CALLBACK_URL=https://api.example.com/twilio/status
TWILIO_INBOUND_WEBHOOK_PUBLIC_URL=https://api.example.com/twilio/inbound
PORT=3000

NGINX reverse proxy (webhook endpoints)

Path: /etc/nginx/conf.d/messaging-api.conf

server {
  listen 443 ssl http2;
  server_name api.example.com;

  ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

  location /twilio/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 10s;
  }
}

Important: signature validation depends on the URL Twilio used; ensure your app uses the external URL, not http://127.0.0.1.

---

Integration Patterns

Pattern: Outbound notifications with delivery-driven fallback

Pipeline:

1. Send SMS with statusCallback.
2. On callback:
   • if delivered: mark success.
   • if undelivered/failed: enqueue email via SendGrid or push notification.

Pseudo-architecture:

• API service: accepts “notify user” request.
• Queue: stores send jobs.
• Worker: sends Twilio message.
• Webhook service: processes status callbacks and triggers fallback.

Example (status callback → SQS):

// on /twilio/status
if (status === "undelivered" || status === "failed") {
  await sqs.sendMessage({
    QueueUrl: process.env.FALLBACK_QUEUE_URL,
    MessageBody: JSON.stringify({ messageSid, to: req.body.To, reason: req.body.ErrorCode }),
  });
}

Pattern: Two-way support with ticketing

Inbound SMS:

• Validate signature.
• Normalize sender (From) and map to customer.
• Create ticket in Jira/ServiceNow/Zendesk.
• Reply with ticket ID via TwiML.

Example TwiML reply:

<Response>
  <Message>Your ticket INC-2048 is open. Reply HELP for options.</Message>
</Response>

Pattern: Keyword-based workflows (HELP/STOP/START + custom)

• HELP: return support URL and contact.
• STOP: update internal preference store (Twilio also blocks).
• Custom keywords: STATUS <id>, ONCALL, ACK <incident>.

Ensure parsing is robust and case-insensitive; log raw inbound payload for audit.

Pattern: Multi-region sending with geo-matching

• Use a single Messaging Service with:
  • sender pool across regions
  • geo-matching enabled
• For compliance, route by recipient country:
  • US/CA: toll-free or A2P 10DLC long code
  • UK: alphanumeric sender ID (if supported) or local number
  • India: DLT constraints (outside scope here; treat as separate compliance module)

Pattern: Idempotent send API

If your upstream retries, you must avoid duplicate SMS.

Approach:

• Accept idempotencyKey from caller.
• Store mapping idempotencyKey -> MessageSid.
• If key exists, return existing MessageSid.

Example DB constraint:

• Unique index on idempotency_key.

---

Error Handling & Troubleshooting

Handle errors at two layers:

• REST API call errors (synchronous)
• Status callback errors (asynchronous delivery failures)

Below are common Twilio errors with root cause and fix.

1) 21211 — invalid To number

Error text (typical):

Twilio could not find a Channel with the specified From address

or:

The 'To' number +1415555 is not a valid phone number.

Root causes:

• Not E.164 formatted.
• Contains spaces/parentheses.
• Invalid country code.

Fix:

• Normalize to E.164 before sending.
• Validate with libphonenumber.
• Reject at API boundary with clear error.

2) 20003 — authentication error

Error text:

Authenticate

or:

Unable to create record: Authenticate

Root causes:

• Wrong TWILIO_AUTH_TOKEN.
• Using test credentials against live endpoint or vice versa.
• Account SID mismatch.

Fix:

• Verify env vars in runtime.
• Rotate token if leaked.
• In CI, ensure correct secret scope.

3) 20429 — rate limit exceeded

Error text:

Too Many Requests

Root causes:

• Bursty sends exceeding Twilio or Messaging Service limits.
• Excessive API polling.

Fix:

• Implement client-side rate limiting and backoff (exponential with jitter).
• Batch sends via queue workers.
• Use Messaging Service / short code for higher throughput.

4) 21610 — recipient opted out

Error text:

The message From/To pair violates a blacklist rule.

Root causes:

• Recipient replied STOP (or carrier-level block).
• Your system keeps retrying.

Fix:

• Suppress sends to opted-out recipients in your DB.
• Provide opt-in flow (START).
• Do not retry 21610; treat as terminal.

5) 30003 — Unreachable destination handset / carrier violation

Error text (common):

Unreachable destination handset

Root causes:

• Device off/out of coverage.
• Carrier filtering.
• Invalid or deactivated number.

Fix:

• Treat as non-retryable after limited attempts.
• Trigger fallback channel.
• Monitor spikes by carrier/country; check A2P registration and content.

6) 30005 — Unknown destination handset

Error text:

Unknown destination handset

Root causes:

• Number not assigned.
• Porting issues.

Fix:

• Mark number invalid after repeated failures.
• Ask user to update phone number.

7) 21614 — 'To' is not a valid mobile number (MMS)

Error text:

'To' number is not a valid mobile number

Root causes:

• Attempting MMS to a number/carrier that doesn’t support MMS.
• Landline.

Fix:

• Detect MMS capability; fallback to SMS with link.
• Use Lookup (Twilio Lookup API) if you must preflight (cost tradeoff).

8) 21606 — From number not capable of sending SMS

Error text:

The From phone number +14155552671 is not a valid, SMS-capable inbound phone number or short code for your account.

Root causes:

• Using a voice-only number.
• Number not owned by your account.
• Wrong sender configured.

Fix:

• Use Messaging Service with verified senders.
• Confirm number capabilities in Console or via IncomingPhoneNumbers API.

9) Webhook signature failures (your logs)

Typical app log:

Invalid signature

Root causes:

• Validating against wrong URL (http vs https, host mismatch, path mismatch).
• Proxy rewrites.
• Body parsing differences.

Fix:

• Validate against the exact public URL configured in Twilio.
• Ensure express.urlencoded() is used for form payloads.
• If behind proxy, set app.set('trust proxy', true) and reconstruct URL carefully.

10) Status callback not firing

Symptoms:

• Message shows delivered in console but your system never receives callback.

Root causes:

• statusCallback not set on message or service.
• Callback URL returns non-2xx; Twilio retries then gives up.
• Firewall blocks Twilio IPs (don’t IP allowlist unless you maintain Twilio ranges).

Fix:

• Set status callback at Messaging Service level.
• Ensure endpoint returns 2xx quickly.
• Log request bodies and response codes; add metrics.

---

Security Hardening

Secrets handling

• Do not store TWILIO_AUTH_TOKEN in repo.
• Use secret manager + short-lived deployment injection.
• Rotate tokens on incident; treat as high-impact credential.

Webhook validation (mandatory)

• Validate X-Twilio-Signature for inbound and status callbacks.
• Reject invalid signatures with 403.
• Log minimal metadata; avoid logging full message bodies if sensitive.

TLS and transport

• Enforce HTTPS for all webhook endpoints.
• Disable TLS 1.0/1.1; prefer TLS 1.2+.
• If using NGINX, follow CIS NGINX Benchmark guidance for strong ciphers (adapt to your org baseline).

Request handling

• Limit request body size (protect against abuse):
  • Express: express.urlencoded({ limit: "64kb", extended: false })
• Apply rate limiting on webhook endpoints (careful: Twilio retries; don’t block legitimate retries).
• Use WAF rules to block obvious abuse, but do not rely on IP allowlists.

Data minimization

• Store only what you need:
  • MessageSid, To, From, timestamps, status, error codes
• If storing message content, encrypt at rest and restrict access.

OS/service hardening (Linux)

• systemd hardening flags (see unit file above).
• Run as non-root user.
• Follow CIS Linux Benchmarks (Ubuntu 22.04 / RHEL/Fedora equivalents):
  • restrict file permissions on env files (chmod 600)
  • audit access to secrets
  • enable automatic security updates where appropriate

---

Performance Tuning

Reduce webhook latency (p95)

Goal: respond to Twilio webhooks in < 200ms p95.

Actions:

• Do not call external services synchronously in webhook handler.
• Enqueue work (SQS/Kafka/Redis) and return 204/200 immediately.
• Pre-parse and validate quickly; avoid heavy logging.

Expected impact:

• Before: webhook handler does DB + ticket creation → 1–3s p95, retries increase load.
• After: enqueue only → <100–200ms p95, fewer retries, lower Twilio webhook backlog.

Throughput scaling for outbound sends

• Use worker pool with concurrency control.
• Implement token bucket rate limiting per Messaging Service / sender type.
• Prefer Messaging Service with appropriate sender (short code/toll-free) for higher throughput.

Expected impact:

• Prevents 20429 spikes and reduces carrier filtering due to bursty patterns.

Cost optimization

• Use Messaging Service geo-matching to reduce cross-region costs where applicable.
• Avoid MMS when SMS + link suffices.
• Use maxPrice carefully; too low increases failures.

Encoding and segmentation

• GSM-7 vs UCS-2 affects segment count and cost.
• If you send non-GSM characters (e.g., emoji, some accented chars), messages may switch to UCS-2 and segment at 70 chars.

Mitigation:

• Normalize content where acceptable.
• Keep messages short; move details to links.

---

Advanced Topics

Idempotency across retries and deploys

Twilio REST messages.create is not idempotent by default. If your worker retries after a timeout, you may double-send.

Mitigations:

• Use an application-level idempotency key stored in DB.
• On timeout, query by your own correlation ID (store in statusCallback query string or in body is not safe). Better:
  • store job ID → message SID mapping once created
  • if create call times out, attempt to detect if message was created by checking Twilio logs is unreliable; prefer conservative “may have sent” handling and alert.

Handling duplicate status callbacks

Twilio may send multiple callbacks for the same status or out of order.

• Store transitions with monotonic state machine:
  • queued < sending < sent < delivered
  • terminal failures: undelivered/failed
• If you receive delivered after undelivered, keep both but treat delivered as final if timestamp is later (rare but possible due to carrier reporting quirks).

Multi-tenant systems

If you operate multiple Twilio subaccounts:

• Store per-tenant Account SID/Auth Token (or use API Keys).
• Validate webhooks per tenant:
  • signature validation uses the tenant’s auth token
  • route by To number or by dedicated webhook URL per tenant

Media URL security for MMS

• Twilio fetches media from your URL; it must be reachable.
• If using signed URLs:
  • TTL must exceed Twilio fetch window (minutes to tens of minutes; be conservative).
• Do not require cookies.
• If you require auth headers, Twilio cannot provide them; use pre-signed URLs.

Compliance gotchas

• Do not send marketing content from unregistered A2P campaigns.
• Maintain HELP/STOP responses and honor opt-out across channels if your policy requires it.
• Keep audit logs for consent (timestamp, source, IP/user agent if applicable).

---

Usage Examples

1) Production outbound SMS with Messaging Service + status tracking (Node)

Files:

• /srv/messaging-api/src/send.js

import "dotenv/config";
import twilio from "twilio";

const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

export async function sendDeployNotification({ to, buildId }) {
  const msg = await client.messages.create({
    messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
    to,
    body: `Build ${buildId} deployed to prod. Reply HELP for support, STOP to opt out.`,
    statusCallback: process.env.TWILIO_STATUS_CALLBACK_URL,
    provideFeedback: true,
  });

  return { sid: msg.sid, status: msg.status };
}

Run:

node -e 'import("./src/send.js").then(m=>m.sendDeployNotification({to:"+14155550123",buildId:"742"}).then(console.log))'

2) Inbound SMS → create ticket → reply with TwiML (FastAPI)

• /srv/messaging-api/app.py

from fastapi import FastAPI, Request, Response
from twilio.request_validator import RequestValidator
from twilio.twiml.messaging_response import MessagingResponse
import os

app = FastAPI()
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])

def create_ticket(from_number: str, body: str) -> str:
    # Replace with real integration
    return "INC-2048"

@app.post("/twilio/inbound")
async def inbound(request: Request):
    form = await request.form()
    signature = request.headers.get("X-Twilio-Signature", "")
    url = os.environ["TWILIO_INBOUND_WEBHOOK_PUBLIC_URL"]

    if not validator.validate(url, dict(form), signature):
        return Response("Invalid signature", status_code=403)

    from_number = form.get("From") or ""
    body = (form.get("Body") or "").strip()

    ticket = create_ticket(from_number, body)

    resp = MessagingResponse()
    resp.message(f"Created {ticket}. Reply HELP for options. Reply STOP to opt out.")
    return Response(str(resp), media_type="text/xml")

Run:

python3.11 -m venv .venv && source .venv/bin/activate
pip install fastapi==0.109.2 uvicorn==0.27.1 twilio==9.4.1 python-multipart==0.0.9
uvicorn app:app --host 0.0.0.0 --port 3000

3) Status callback → metrics + fallback enqueue (Express)

• /srv/messaging-api/src/status.js

import express from "express";
import twilio from "twilio";

const app = express();
app.use(express.urlencoded({ extended: false, limit: "64kb" }));

app.post("/twilio/status", async (req, res) => {
  const signature = req.header("X-Twilio-Signature") || "";
  const url = process.env.TWILIO_STATUS_CALLBACK_PUBLIC_URL;

  const ok = twilio.validateRequest(process.env.TWILIO_AUTH_TOKEN, signature, url, req.body);
  if (!ok) return res.status(403).send("Invalid signature");

  const { MessageSid, MessageStatus, ErrorCode, To } = req.body;

  // Example: emit metric
  console.log("twilio_status", { MessageSid, MessageStatus, ErrorCode });

  if (MessageStatus === "failed" || MessageStatus === "undelivered") {
    // enqueue fallback (pseudo)
    console.log("enqueue_fallback", { to: To, messageSid: MessageSid, reason: ErrorCode });
  }

  res.status(204).send();
});

app.listen(3000);

4) MMS with signed URL (S3 presigned) + fallback to SMS link

Pseudo-flow:

• Generate presigned URL valid for 2 hours.
• Send MMS with media URL.
• If status callback returns 21614 or undelivered, send SMS with link.

Python snippet:

msg = client.messages.create(
    messaging_service_sid=os.environ["TWILIO_MESSAGING_SERVICE_SID"],
    to="+14155550123",
    body="Incident screenshot attached.",
    media_url=[presigned_url],  # TTL >= 2h
    status_callback="https://api.example.com/twilio/status",
)

Fallback SMS body:

MMS failed on your carrier. View: https://app.example.com/incidents/INC-2048

5) Opt-out aware bulk send with concurrency + suppression

• Load recipients.
• Filter out opted-out in DB.
• Send with concurrency 20.
• On 21610, mark opted-out.

Node (sketch):

import pLimit from "p-limit";
import twilio from "twilio";

const limit = pLimit(20);
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

async function sendOne(to) {
  try {
    return await client.messages.create({
      messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
      to,
      body: "Maintenance tonight 01:00-02:00 UTC. Reply STOP to opt out.",
      statusCallback: process.env.TWILIO_STATUS_CALLBACK_URL,
    });
  } catch (e) {
    const code = e?.code;
    if (code === 21610) {
      // mark opted out
      return null;
    }
    throw e;
  }
}

await Promise.all(recipients.map((to) => limit(() => sendOne(to))));

Install:

npm install p-limit@5.0.0 twilio@4.23.0

---

Quick Reference

Task	Command / API	Key flags / fields
Send SMS (CLI)	twilio api:core:messages:create	--to, --from or --messaging-service-sid, --body, --status-callback, --provide-feedback, --max-price
Send MMS (CLI)	twilio api:core:messages:create	--media-url (repeatable), --body
Fetch message	twilio api:core:messages:fetch --sid SM...	--sid
List messages	twilio api:core:messages:list	--to, --from, --limit
Create Messaging Service	twilio api:messaging:v1:services:create	--friendly-name, --status-callback
Update service webhooks	twilio api:messaging:v1:services:update	--inbound-request-url, --inbound-method, --status-callback
Attach number to service	twilio api:messaging:v1:services:phone-numbers:create	--service-sid, --phone-number-sid
Inbound webhook	HTTP POST /twilio/inbound	Validate X-Twilio-Signature, parse form fields
Status callback	HTTP POST /twilio/status	MessageSid, MessageStatus, ErrorCode

---

Graph Relationships

DEPENDS_ON

• twilio SDK (Node 4.23.0 / Python 9.4.1)
• Public HTTPS ingress (NGINX/ALB/API Gateway)
• Persistent store for idempotency and message state (Postgres/DynamoDB)
• Queue for async processing (SQS/Kafka/Redis Streams) recommended

COMPOSES

• twilio-voice (IVR can trigger SMS follow-ups; missed-call → SMS)
• twilio-verify (OTP via SMS; share webhook infra and signature validation patterns)
• sendgrid-email (fallback channel on undelivered; unified notification service)
• observability (metrics/logging/tracing for webhook latency and delivery rates)

SIMILAR_TO

• aws-sns-sms (SMS sending + delivery receipts, different semantics)
• messagebird-sms / vonage-sms (carrier routing + webhook patterns)
• firebase-cloud-messaging (delivery callbacks conceptually similar, different channel)