Canonical source: docs/claude/twilio-a2p-onboarding-template.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.
Twilio A2P 10DLC Onboarding — per-provider SMS enablement template
Purpose: Every clinic that wants to send SMS (marketing lifecycle sequences + blasts) must be registered with Twilio's A2P 10DLC program before a single message will deliver in the US. This is a per-provider registration (Brand → Campaign → Messaging Service → number). Use this template to (1) collect the info from the clinic during onboarding, and (2) submit it to Twilio. Approval takes days → ~2 weeks; registration carries over if a number is ported with the same brand/campaign.
Optional onboarding task: only needed if the clinic wants SMS. Email (MailerSend) has no equivalent gate.
Part 1 — BRAND registration (the business). Collect from the clinic:
| Field | Notes |
|---|---|
| Legal business name | Exactly as registered with the IRS |
| Business EIN / Tax ID | US EIN (or local equivalent). Sole proprietors have a lighter flow |
| Business type | Private / Public / Non-profit / Government |
| Industry / vertical | e.g. Healthcare |
| Registered business address | Street, city, state, ZIP, country |
| Business website | Must be live and describe the services |
| Support email + phone | Reachable; used for verification |
| Authorized contact | Name, email, job title, phone |
| Stock ticker + exchange | Public companies only |
Part 2 — CAMPAIGN registration (the messaging use case). Collect/prepare:
| Field | Notes / our defaults |
|---|---|
| Use case | Mixed / Marketing (lifecycle + promotional). "Low Volume Mixed" for small clinics |
| Campaign description | What the clinic texts patients about (appointment follow-ups, review requests, re-engagement, promotions) |
| Sample messages (2–3, real) | Must match what we actually send, incl. brand name + opt-out. e.g. "{Clinic}: Thanks for visiting! Mind sharing quick feedback? {link} Reply STOP to opt out." |
| Opt-in description | HOW consent is collected — must be explicit for marketing. Ours: checkbox at booking / lead capture with SMS consent language; describe the flow + provide the URL/screenshot |
| Opt-in message | The confirmation text sent after opt-in |
| Opt-out keywords | STOP (+ STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) — our compliant-send layer honors these |
| Help keywords | HELP / INFO → returns clinic contact |
| Message frequency | e.g. "Up to ~4/month" |
| Embedded links / phone numbers | Yes (booking links) — declare it |
| Age-gated / affiliate / direct-lending content | No (declare) |
Part 3 — Provisioning (Twilio side, per clinic)
- Create/verify Brand (Part 1) → Twilio + TCR vetting.
- Create Campaign (Part 2) under the brand → carrier approval.
- Create a Messaging Service, attach the campaign, add the clinic's phone number (new or ported — porting keeps the registration).
- Enable Advanced Opt-Out on the Messaging Service (STOP/HELP auto-handling) — our layer also enforces suppression app-side.
- Store the clinic's Messaging Service SID →
clinicsv2/{clinic}/messaging_numbers(what our SMS sender reads).
What's already handled on OUR side (so the clinic doesn't re-implement)
- Consent capture (explicit for SMS), STOP/HELP handling, suppression, quiet-hours (marketing), rate-limit, dedup — the compliant-send gateway (#517).
- The clinic only owes Twilio the registration data above + a verified number.
Gaps / to confirm with main agent
- Is there a self-serve intake form in Settings → Integrations that captures Part 1 + Part 2 and files it? If not, that's the onboarding build. Today this is a manual submission.
- Per-number → clinic mapping lives in
messaging_numbers; confirm the SMS sender reads the Messaging Service SID from there.