Skill v1.0.0
Trusted Publisher100/100version: "1.0.0" name: twilio-numbers-senders description: > Choose the right Twilio number type and sender BEFORE building. Covers phone numbers (local, toll-free, short code, mobile), alphanumeric sender IDs, WhatsApp senders, RCS agents, international availability, and regulatory bundles. Each number type has its own compliance program — choosing wrong means rebuilding. Use this skill first.
Overview
Choosing 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)
US Number Types — Comparison
| 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
Compliance Programs Per Number Type
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.
How to Choose (US)
- Need voice + SMS from same number? → Local (10DLC) or toll-free. Short codes are SMS-only.
- Marketing at scale (>15 SMS/sec)? → Short code (highest throughput) or 10DLC with secondary vetting + Messaging Service number pool
- Fastest time to send? → Toll-free (3-5 day verification) or Twilio Verify (immediate, no registration)
- Customer support with local presence? → Local number in customer's area code
- Transactional notifications? → Toll-free (simpler registration) or 10DLC
- Verification OTPs? → Twilio Verify (exempt from A2P, built-in Fraud Guard)
- Budget-constrained? → 10DLC (lowest cost) — but plan for 10-15 day registration
Non-Phone Senders
Alphanumeric Sender IDs
A branded name (up to 11 characters) displayed instead of a phone number. One-way only — recipients cannot reply.
- Not supported in the US or Canada
- Supported in 100+ countries; some require pre-registration with documentation
- Some carriers impose minimum length — short IDs may display as "unknown"
- Add to Messaging Services for automatic sender selection by destination country
Docs: Alpha Sender in Messaging Services | International support by country | How to register
WhatsApp Business Senders
A phone number registered with Meta's WhatsApp Business Platform via Twilio.
- Requires WABA (WhatsApp Business Account) + sender approval
- Outbound requires pre-approved Message Templates (outside 24-hour service window)
- Direct customers: self-service Console signup or Senders API
- ISVs: Meta Tech Provider Program for customer onboarding
Docs: WhatsApp hub | Getting started | Self sign-up
RCS Agents
Branded sender with logo, rich cards, carousels, and suggested actions. Falls back to SMS automatically.
- Requires carrier-level approval per country
- Testing phase: RCS only delivers to added test devices; others get SMS fallback
- Each RCS sender can only belong to ONE Messaging Service
Docs: RCS onboarding | RCS compliance guide | Regional availability
Voice Trust: Number Reputation Programs
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
Branded Calling: Prerequisites & Display Standards
The call trust stack is layered — each product builds on the one below:
Layer 4: Enhanced Branded Calling (name + logo + call reason)↑ requiresLayer 3: Basic Branded Calling (business name display)↑ requiresLayer 2: Voice Integrity (spam label remediation)↑ requiresLayer 1: SHAKEN/STIR (attestation — auto-applied with approved profile)↑ requiresLayer 0: Primary Customer Profile (Trust Hub business identity)
Prerequisites for Basic Branded Calling:
- Approved Primary Customer Profile in Trust Hub (EIN, business name, address, authorized rep) — 1-3 business days
- SHAKEN/STIR — automatic once profile is approved
- Signed Letter of Authorization (LOA) for the phone numbers
- Basic Branded Calling trust product submitted + approved — 2-4 weeks
Additional prerequisites for Enhanced Branded Calling:
- Approved Voice Integrity trust product — 3-7 business days carrier propagation
- Enhanced Branded Calling trust product — 3-6 weeks
Phone number eligibility:
- Local and mobile numbers only — toll-free numbers are NOT eligible
- Must be Twilio-owned (not ported-in numbers pending transfer)
- Calls must originate via Programmable Voice (API or TwiML) — SIP Trunking calls are not branded
- Each number can only belong to one Branded Calling trust product at a time
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:
- Must match registered business name or documented trade name/DBA
- No phone numbers, URLs, or special characters
- Misleading names are rejected during review
Call reason guidelines (Enhanced only):
- Must accurately describe the call purpose
- Cannot be generic ("Important Call") or misleading
- Set per trust product — cannot be changed per-call
- Keep under 40 characters for consistent carrier display
Carrier support:
- T-Mobile: Basic + Enhanced (native)
- AT&T, Verizon: Voice Integrity spam remediation; Branded Calling display expanding
- Apple/iOS: Enhanced only, limited support
CNAM (traditional caller ID): 15-character limit, text-only, works on landlines, propagates in 24-48 hours, no approval process needed.
International Numbers
- ~25 countries have GA (self-service) SMS numbers. Many major markets are Private Offering — requires a request form and 1-6 week delivery.
- MMS only available in US, Canada, and Australia. Use WhatsApp or RCS for rich media elsewhere.
- Many countries require Regulatory Bundles (identity/address verification) before provisioning numbers. Non-compliant numbers risk deprovisioning.
Docs: Country SMS guidelines | Regulatory compliance | How to submit a bundle | Country regulatory requirements
CANNOT
Phone Numbers
- No mobile number type in the US —
availablePhoneNumbers('US').mobile.list()returns 404. US numbers are classified as local or toll-free only. - Cannot use both `voiceApplicationSid` and `voiceUrl` — Setting one auto-clears the other. Same for
smsApplicationSidvssmsUrl. - Cannot use `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. - Geographic search is US/Canada only —
nearNumber,nearLatLong,inPostalCode,inRegion,inRateCenter,inLataare ignored for non-US/CA numbers. - No undo for number release — Once released, the number goes back to the pool. No grace period or reclaim mechanism.
- Address required for many international numbers —
addressRequirementscan benone,any,local, orforeign. Purchase fails without the required address/bundle.
Voice Trust
- Cannot guarantee call delivery — Carrier spam filters operate independently. Even Level A + Branded Calling + Voice Integrity can still be filtered.
- Cannot brand inbound calls — Branded Calling applies to outbound calls only.
- Cannot use Voice Integrity or Branded Calling outside the US — Voice Integrity and Branded Calling are currently US-only. STIR/SHAKEN is available in the US and Canada (CRTC-mandated since Nov 2021).
- Cannot bypass manual approval — Trust Hub vetting involves human review (1-3 business days for profiles, 2-6 weeks for Branded Calling).
- Cannot preserve attestation through `<Dial>` — CallToken forwarding requires the Calls API or Conference Participants API.
- Cannot use Branded Calling with SIP Trunking — Calls must originate via Programmable Voice.
- Cannot use toll-free numbers with Branded Calling — Local and mobile numbers only.
Common Mistakes
- Buying numbers before understanding compliance — Each number type has its own registration program. Choosing 10DLC means 10-15 days of A2P registration before you can send.
- Using local numbers for marketing without A2P — Messages get filtered (error 30034). All US 10DLC requires A2P registration.
- Expecting toll-free to work immediately — Unverified toll-free numbers cannot send SMS to US/Canada at all.
- Assuming MMS works internationally — Only US, Canada, Australia. Use WhatsApp or RCS elsewhere.
- Choosing short code for voice — Short codes are SMS/MMS only. No voice capability.
Next Steps
- Register your numbers:
twilio-compliance-onboarding - Set up Messaging Services with number pools:
twilio-messaging-services - Follow traffic rules after registration:
twilio-compliance-traffic - WhatsApp sender management:
twilio-whatsapp-manage-senders