Skill v1.0.0

version: "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

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:

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)
         ↑ 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:

1. Approved Primary Customer Profile in Trust Hub (EIN, business name, address, authorized rep) — 1-3 business days
2. SHAKEN/STIR — automatic once profile is approved
3. Signed Letter of Authorization (LOA) for the phone numbers
4. Basic Branded Calling trust product submitted + approved — 2-4 weeks

Additional prerequisites for Enhanced Branded Calling:

1. Approved Voice Integrity trust product — 3-7 business days carrier propagation
2. 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:

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 smsApplicationSid vs smsUrl.
• 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, inLata are 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 — addressRequirements can be none, any, local, or foreign. 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

1. 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.
2. Using local numbers for marketing without A2P — Messages get filtered (error 30034). All US 10DLC requires A2P registration.
3. Expecting toll-free to work immediately — Unverified toll-free numbers cannot send SMS to US/Canada at all.
4. Assuming MMS works internationally — Only US, Canada, Australia. Use WhatsApp or RCS elsewhere.
5. 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