Skip to content

twilio.md

Latest commit

 

History

History
152 lines (106 loc) · 4.5 KB

twilio.md

File metadata and controls

152 lines (106 loc) · 4.5 KB

Twilio

Programmable communications platform: SMS, MMS, WhatsApp, voice, email (via SendGrid). The default low-level API for custom SMS builds, transactional messaging, and B2B SaaS embedding SMS into products.

Capabilities

Integration Available Notes
API ✓ REST API, well-documented, mature
MCP - Not available natively (community wrappers exist)
CLI ✓ Official twilio CLI
SDK ✓ Node, Python, Ruby, PHP, Java, Go, C#, .NET

Authentication

  • Type: Basic auth with Account SID + Auth Token (or API Key SID + Secret)
  • Header: Authorization: Basic base64(AccountSID:AuthToken)
  • Get credentials: https://console.twilio.com → Account Info
  • Recommendation: Use API Keys (revocable, scoped) for production rather than the master Auth Token

Common Agent Operations

Send SMS

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json

To=+15551234567
From=+15559876543
Body=Hello from Twilio

Send MMS

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json

To=+15551234567
From=+15559876543
Body=Check this out
MediaUrl=https://example.com/image.jpg

List messages

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json?PageSize=50

Get message status

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json

Status values: queued, sending, sent, delivered, undelivered, failed.

List phone numbers

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json

Buy a phone number

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json

PhoneNumber=+15559876543

Configure webhook for inbound messages

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json

SmsUrl=https://your-app.com/sms-webhook
SmsMethod=POST

Inbound SMS POSTs to the webhook with: From, To, Body, MessageSid, NumMedia, etc.

A2P 10DLC registration (US)

# Create brand
POST https://messaging.twilio.com/v1/a2p/BrandRegistrations

CustomerProfileBundleSid=...
A2PProfileBundleSid=...

# Create campaign
POST https://messaging.twilio.com/v1/Services/{ServiceSid}/Compliance/Usa2p

BrandRegistrationSid=...
Description=...
MessageSamples[]=Sample text 1
MessageFlow=Opt-in flow description
UseCase=MARKETING

Most workflows are clearer in the Console UI. Programmatic registration is for high-scale platforms managing many brands.

API Pattern

REST + form-encoded request bodies (not JSON for most endpoints). Resources nested under Account: /Accounts/{AccountSid}/.... Pagination via Page, PageSize, NextPageUri.

Key Concepts

  • Messaging Service: virtual sender container; load-balances across multiple numbers, handles A2P registration grouping
  • Sticky Sender: same recipient always receives from the same number within a service
  • Geo-Match: route to a number matching the recipient's country/region
  • Status Callback: webhook fired on every delivery state change
  • Carrier Lookup: pre-send check for line type (mobile, landline, VoIP) — costs ~$0.005

Pricing

  • US 10DLC SMS: $0.0079/msg
  • US toll-free SMS: $0.0079/msg
  • US short code SMS: $0.0079/msg + $1,000/mo lease
  • MMS: ~$0.02
  • Carrier surcharges (~$0.005 US 10DLC)
  • A2P 10DLC: ~$15 brand + $10/mo per campaign
  • Phone number rental: $1.15/mo (10DLC) to $2/mo (toll-free)

Rate Limits

  • Default: 1 msg/sec on long codes (10DLC trust score raises this to 4–100+)
  • Short code: 100+ msg/sec
  • Messaging Services throttle automatically
  • Carrier filtering applies above contracted throughput

When to Use

  • Building custom SMS flows into a product (B2B SaaS, mobile apps)
  • Transactional and auth SMS (OTPs, alerts, notifications)
  • Multi-channel orchestration (SMS + voice + WhatsApp)
  • High-volume programmable messaging
  • When you need full control and minimal abstraction
  • Backing store for Customer.io / Segment / other orchestration layers

When NOT to Use

  • DTC ecom marketing flows — use Klaviyo, Postscript, or Attentive (better tooling for cart recovery, segments, A/B tests)
  • If you don't want to handle compliance plumbing — Twilio gives you primitives, not policy
  • Marketing UI for non-technical users — there isn't one

Relevant Skills

  • sms
  • emails (transactional sister product via SendGrid)
  • onboarding (post-signup SMS milestones)