Twilio API (SMS, Voice, Verify) — SKILL.md

---
name: "Twilio API (SMS, Voice, Verify)"
description: "Integrate Twilio: SMS/MMS sending, A2P 10DLC registration, phone verification (Verify API), voice/IVR (TwiML), Conversations, phone number management, TCPA/GDPR compliance, pricing, and alternatives (MessageBird, Vonage, Plivo)."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["twilio", "sms", "voice", "verification", "messaging", "saas"]
---

# Twilio API (SMS, Voice, Verify)

---
name: "Twilio API (SMS, Voice, Verify)"
description: "Integrate Twilio: SMS/MMS sending, A2P 10DLC registration, phone verification (Verify API), voice/IVR (TwiML), Conversations, phone number management, TCPA/GDPR compliance, pricing, and alternatives ("
version: "1.0.0"
author: "skynet"
category: "dev"
tags: ["twilio", "sms", "voice", "verification", "messaging", "saas"]
---

I will search for any existing Twilio integrations or documentation within the codebase to ensure the technical reference aligns with any established patterns in the project.
# Twilio Integration Reference for SaaS Applications

This guide provides a technical overview of integrating Twilio into SaaS platforms, covering SMS, Voice, Verify, and compliance requirements.

---

## 1. SMS: Programmable Messaging
For high-volume SaaS messaging, use the **Messaging Service** SID (`MGXXX`) instead of a single phone number to enable features like sticky sender and alpha-numeric IDs.

### Sending Messages
```python
from twilio.rest import Client

client = Client(account_sid, auth_token)

message = client.messages.create(
    messaging_service_sid='MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    to='+15558675310',
    body='Your appointment is confirmed for 3:00 PM.',
    status_callback='https://myapp.com/webhooks/sms-status'
)
```

### Key Concepts
- **A2P 10DLC (US Only):** Mandatory registration for application-to-person messaging via standard 10-digit long codes. Requires "Brand" and "Campaign" registration to avoid heavy carrier filtering.
- **Toll-Free Numbers:** Good for lower-volume needs; require "Toll-Free Verification" but are easier to set up than 10DLC.
- **Short Codes:** 5-6 digit numbers for massive scale (100+ TPS). High cost ($500-$1000/mo).
- **Status Callbacks:** Essential for tracking delivery. States: `queued`, `sent`, `delivered`, `undelivered`, `failed`.

---

## 2. VOICE: Programmable Voice
Voice interaction is driven by **TwiML** (Twilio Markup Language) — an XML-based instruction set.

### Making a Call
```python
call = client.calls.create(
    url='https://handler.twilio.com/twiml/EHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    to='+15558675310',
    from_='+15552223333'
)
```

### Receiving a Call (Webhook Handler)
Your server returns TwiML instructions:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="Polly.Joey">Welcome to our support line.</Say>
    <Gather input="dtmf" timeout="5" numDigits="1" action="/handle-key">
        <Say>Press 1 for Sales, 2 for Support.</Say>
    </Gather>
    <Record maxLength="30" action="/handle-recording"/>
</Response>
```

---

## 3. VERIFY: Phone Verification
Do not "roll your own" SMS verification logic (generating codes, storing them in Redis, etc.). Use the **Verify API** for better deliverability and global compliance.

- **Channels:** SMS, Voice, Email, WhatsApp, TOTP, and Silent Network Auth (SNA).
- **Silent Network Auth:** Verifies the phone number via the carrier data connection without requiring the user to type a code.

```python
# Send Verification
verification = client.verify \
    .v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX') \
    .verifications \
    .create(to='+15558675310', channel='sms')

# Check Verification
verification_check = client.verify \
    .v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX') \
    .verification_checks \
    .create(to='+15558675310', code='123456')
```

---

## 4. CONVERSATIONS
The Conversations API abstracts away the "channel" (SMS vs WhatsApp vs In-App Chat), allowing you to maintain a single thread of history.

- **Participants:** You can add a `whatsapp:+1...` and an `sms:+1...` to the same conversation.
- **Scoping:** Best for 1:1 or 1:Many persistent chat (e.g., support tickets).

---

## 5. PHONE NUMBERS & COMPLIANCE
### Regulatory Requirements
Each country has different requirements (Proof of Identity, Proof of Address). Twilio's **Regulatory Compliance API** allows you to submit these programmatically.

### Porting
Porting numbers from other carriers into Twilio takes 1–4 weeks. Start this early in the migration process.

---

## 6. GLOBAL COMPLIANCE (TCPA/GDPR)
- **TCPA (US):** Requires explicit opt-in for marketing messages. Twilio handles `STOP`, `UNSUBSCRIBE`, and `START` keywords automatically at the carrier level.
- **GDPR (EU):** Ensure PII (phone numbers) in logs are handled according to your data processing agreement.
- **A2P 10DLC:** Throughput (`TPS`) is determined by your "Trust Score" during registration.

---

## 7. PRICING MODEL
| Category | Metric | Approx. Cost (US) |
| :--- | :--- | :--- |
| **SMS** | Per segment (160 chars) | ~$0.0079 |
| **Voice** | Per minute | ~$0.0130 (Inbound), ~$0.0150 (Outbound) |
| **Verify** | Per successful verification | ~$0.05 |
| **Numbers** | Per month | ~$1.15 (Local), ~$2.15 (Toll-Free) |

---

## 8. SDKs
Twilio supports all major languages. Direct REST API calls are also straightforward if you prefer minimal dependencies.
- **Node.js:** `npm install twilio`
- **Python:** `pip install twilio`
- **Ruby:** `gem install twilio-ruby`
- **C#:** `dotnet add package Twilio`

---

## 9. ALTERNATIVES
- **Vonage (Nexmo):** Stronger in APAC/Europe; often cheaper than Twilio.
- **MessageBird:** Excellent for Omnichannel (WhatsApp/Line/WeChat).
- **AWS SNS/Pinpoint:** Best if you are already heavily in the AWS ecosystem and need high-volume, low-cost "firehose" SMS.
- **Telnyx:** Often preferred by engineers for its better UI, lower pricing, and more "direct-to-carrier" feel.

---

## 10. CRITICAL "GOTCHAS"
1.  **Segments vs Messages:** 160 characters = 1 segment. Using emojis or non-GSM characters (Unicode) drops segments to **70 characters**.
2.  **Carrier Filtering:** If your messages aren't arriving but show as `sent` in Twilio, the carrier (Verizon/AT&T) is likely filtering them. Check your 10DLC registration.
3.  **E.164 Formatting:** Always store phone numbers in E.164 format (`+15558675310`).
4.  **Quiet Hours:** Avoid sending non-urgent messages during the recipient's local night time to reduce opt-outs and complaints.
5.  **Rate Limits:** Default REST API limit is 100 requests per second. Messaging throughput (TPS) is separate and depends on your number type/brand.