twilio-numbers-senders

Imported from openai/plugins (plugins/twilio-developer-kit/skills/twilio-numbers-senders/SKILL.md). Install upstream with npx skills add openai/plugins --skill twilio-numbers-senders. Copyright stays with the author.

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