# Twilio (optional: SMS)

Twilio sends text messages from your app. It is **optional and off by default**. Everything else works without it.

**Time:** 30 minutes to register, then **weeks** of waiting. **Needs:** a Twilio account, a payment method, and a decision on brand type (see below).

## Slow prerequisites (read this first)

US text messages need **A2P 10DLC registration**: a Brand, then a Campaign, each reviewed by humans.

- Expect **2 to 4 weeks** from submit to approved (unverified; reports vary from about 7 business days to over a month).
- You cannot speed it up. SMS stays off until approved. Everything else keeps working.
- **Brand type trap:** a US LLC always has an EIN, so it cannot use the cheaper sole-proprietor brand. Solo founders without a company can. A wrong type means registering again and paying again. Decide before you start.
- Sole-proprietor limits: one brand, one campaign, one phone number.

## Steps

1. Sign up at <https://www.twilio.com> and add billing.
2. From the console's Account Dashboard copy the **Account SID** (starts with `AC`) and **Auth token**. Save them in Vault (below).
3. Register your Brand and Campaign for A2P 10DLC in the Twilio console, following Twilio's own guide: <https://www.twilio.com/docs/messaging/compliance/a2p-10dlc>. Do this early; it is the slow part.
4. After approval, create a **Messaging Service** named exactly `factory` (or rename the one your campaign is on to `factory`) and copy its SID (starts with `MG`). Add it in Vault. The factory then adds each app's number to it.

You do not buy numbers yourself. The factory buys each app its own number, names it `factory:<app>` in Twilio, and never touches numbers it did not buy.

**Least privilege:** the Auth token has full account access, and the factory expects the Account SID and Auth token. Rotate the Auth token if it leaks, and use a Twilio account only for this.

Until the campaign is approved, leave the Messaging Service SID empty. US carriers block texts from the apps' numbers in the meantime, and each run that texts shows a card saying so.

## Where it goes

Console → **Settings → Vault** → card **Twilio**:

| Field | Secret |
|---|---|
| **Account SID** | `TWILIO_ACCOUNT_SID` |
| **Auth token** | `TWILIO_AUTH_TOKEN` |
| **Messaging Service SID (A2P)** (optional until approved) | `TWILIO_MESSAGING_SERVICE_SID` |

Then allow SMS in **Settings → Budget** (the `sms` switch is off by default).

## What it gates

SMS features in your apps. Nothing else.

## What it costs

Estimates (unverified; check Twilio's pricing pages): Brand registration about $4.50 once; campaign vetting about $15 once; campaign about $2 to $10 a month; phone number about $1.15 a month; each message a fraction of a cent plus carrier surcharges. About $26 up front plus about $6 a month for a small app is a planning figure. The factory books an estimated $5 a month against your budget.

## Common problems

"Registration submitted" is not "approved". Check status in the Twilio console. If the brand type was wrong, you must register again.