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.