Terminal
Terminal/Skill
Helps developers pick the right Twilio number type or sender, such as local, toll-free, short code or WhatsApp, before they build.
By Twilio
Works with
npx skills add twilio/ai --skill twilio-numbers-sendersChoosing the right number type and sender is the first decision in any Twilio project. Each number type comes with its own compliance/verification program, throughput limits, and capabilities. Developers who skip this step buy numbers first, build their app, then discover they chose the wrong type.
Lifecycle: Choose numbers/senders (this skill) → Register them (twilio-compliance-onboarding) → Follow traffic rules (twilio-compliance-traffic)
| Local (10DLC) | Toll-Free (800/888/877) | Short Code (5-6 digits) | |
|---|---|---|---|
| SMS | Yes | Yes | Yes |
| MMS | Yes | Yes | Yes |
| Voice | Yes | Yes | No |
| Two-way | Yes | Yes | Yes |
| Throughput | ~1-75+ SMS/sec (varies by trust score) | ~3 SMS/sec | 10-100 SMS/sec |
| Compliance program | A2P 10DLC (brand + campaign) | Toll-Free Verification | Pre-approved at purchase (carrier review) |
| Approval timeline | 10-15 business days | 3-5 business days | 8-12 weeks provisioning |
| Best for | Transactional, marketing, support | Notifications, support, verification | High-volume marketing, 2FA |
| Cost | Lowest | Medium | Highest (setup + monthly + per-msg) |
Source: US/Canada SMS comparison
Every US number type requires its own verification before traffic flows:
Local 10DLC → A2P 10DLC registration: Brand registration (EIN, business identity) + Campaign registration (use case, sample messages, opt-in flow). Trust Score determines throughput. Sole Proprietors: ~1 SMS/sec, 1 campaign. Standard: ~15+ SMS/sec, scales with secondary vetting. A2P overview | Quickstart
Toll-Free → Toll-Free Verification (TFV): Business name, website, use case description, sample messages, opt-in type. Unverified toll-free numbers cannot send SMS to US/Canada. Console onboarding | Requirements
Short Code → Carrier review at purchase: Application reviewed during 8-12 week provisioning. Available in 14 countries: US, Canada, UK, Germany, France, India, Brazil, Mexico, Argentina, Colombia, Dominican Republic, New Zealand, Spain, Sweden. Short code guidelines by country | What is a short code?
Twilio Verify → Exempt. No registration needed — Verify handles compliance automatically.
See twilio-compliance-onboarding for full registration details and gotchas.
A branded name (up to 11 characters) displayed instead of a phone number. One-way only — recipients cannot reply.
Docs: Alpha Sender in Messaging Services | International support by country | How to register
A phone number registered with Meta's WhatsApp Business Platform via Twilio.
Docs: WhatsApp hub | Getting started | Self sign-up
Branded sender with logo, rich cards, carousels, and suggested actions. Falls back to SMS automatically.
Docs: RCS onboarding | RCS compliance guide | Regional availability
If making outbound voice calls, these programs improve answer rates:
| Program | What it does | Carriers | Prerequisites |
|---|---|---|---|
| STIR/SHAKEN | Level A attestation = trusted caller ID | US and Canada | Trust Hub Business Profile + EIN |
| Voice Integrity | Remediates spam/scam labels | T-Mobile, AT&T, Verizon (coming) | Approved Business Profile + US address |
| Branded Calling | Shows name + logo on caller ID | T-Mobile, Verizon (Public Beta) | STIR/SHAKEN + Trust Hub profile |
| CNAM | Displays business name on caller ID | US long codes only (not toll-free) | EIN or DUNS number |
Priority order: STIR/SHAKEN first (required for Level A attestation) → Voice Integrity (spam label remediation) → Branded Calling (visual caller ID, mobile only) → CNAM (simplest, lowest impact, landlines by default).
Docs: STIR/SHAKEN overview | Voice Integrity overview | Branded Calling overview | CNAM overview
The call trust stack is layered — each product builds on the one below:
Layer 4: Enhanced Branded Calling (name + logo + call reason)
↑ requires
Layer 3: Basic Branded Calling (business name display)
↑ requires
Layer 2: Voice Integrity (spam label remediation)
↑ requires
Layer 1: SHAKEN/STIR (attestation — auto-applied with approved profile)
↑ requires
Layer 0: Primary Customer Profile (Trust Hub business identity)
Prerequisites for Basic Branded Calling:
Additional prerequisites for Enhanced Branded Calling: 5. Approved Voice Integrity trust product — 3-7 business days carrier propagation 6. Enhanced Branded Calling trust product — 3-6 weeks
Phone number eligibility:
Display standards:
| Asset | Basic | Enhanced |
|---|---|---|
| Display name | Business name, ~32 char carrier limit, must match Trust Hub profile | Same |
| Logo | N/A | Square, min 300x300px, max 1MB, PNG/JPG, no text overlays |
| Call reason | N/A | Free-text, ~40 char carrier display limit (e.g., "Appointment Reminder") |
Display name rules:
Call reason guidelines (Enhanced only):
Carrier support:
CNAM (traditional caller ID): 15-character limit, text-only, works on landlines, propagates in 24-48 hours, no approval process needed.
Docs: Country SMS guidelines | Regulatory compliance | How to submit a bundle | Country regulatory requirements
availablePhoneNumbers('US').mobile.list() returns 404. US numbers are classified as local or toll-free only.voiceApplicationSid and voiceUrl — Setting one auto-clears the other. Same for smsApplicationSid vs smsUrl.voiceApplicationSid and trunkSid simultaneously — Setting one auto-deletes the other.contains pattern requires minimum 2 characters — Single-character patterns return 400. Wildcards * mid-pattern also fail.nearNumber, nearLatLong, inPostalCode, inRegion, inRateCenter, inLata are ignored for non-US/CA numbers.addressRequirements can be none, any, local, or foreign. Purchase fails without the required address/bundle.<Dial> — CallToken forwarding requires the Calls API or Conference Participants API.twilio-compliance-onboardingtwilio-messaging-servicestwilio-compliance-traffictwilio-whatsapp-manage-senders