> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio

> Connect Twilio to KnoxCall for SMS alerts and phone verification — a dedicated subaccount, the Account SID and Auth Token, a sending number, and the Verify service without which no new SMS alert destination can be added.

# Twilio

Twilio sends KnoxCall's **SMS alert notifications** and runs the **phone verification** that proves a number belongs to someone before it can receive them.

**Scope: Global defaults.** SMS is sent on the platform credential. On KnoxCall Cloud that is KnoxCall's Twilio account and there is nothing for you to configure; on a self-hosted deployment save your account under **Global defaults**. The card is also offered under *This tenant*, but a workspace-scoped Twilio row is not used for alert SMS today — save it at platform scope.

**Before you start**

* A Twilio account with billing enabled.
* Admin rights on it: the credential below is a full-account credential.

## 1. In Twilio

Twilio has no scoped API keys for messaging: the **Account SID + Auth Token** pair is the whole account. Contain the blast radius with a subaccount.

1. **Twilio Console → Account → Subaccounts → Create subaccount** named for KnoxCall. (Skip only if you accept that a leaked token controls your whole Twilio account.)
2. Switch into the subaccount. On its dashboard copy the **Account SID** (`AC…`) and reveal and copy the **Auth Token**.
3. **Phone Numbers → Buy a number** (or move one into the subaccount) with **SMS** capability. Note it in E.164 form, e.g. `+14155552671`. Some countries require a registered sender ID or a 10DLC/toll-free registration before SMS is delivered — Twilio's number page says so.
4. **Verify → Services → Create new**. Friendly name `KnoxCall`; leave **Fraud Guard** on — it is the anti-SMS-pumping control this exists for. Copy the **Service SID** (`VA…`).

## 2. Enter it in KnoxCall

**Settings → Integrations → Global defaults → Twilio** → *Configure*:

| Field                  | Value                         |
| ---------------------- | ----------------------------- |
| **Account SID**        | `AC…` — the subaccount's SID  |
| **Auth token**         | The subaccount's Auth Token   |
| **From number**        | The SMS-capable number, E.164 |
| **Verify Service SID** | `VA…`                         |

Fill in all four and **Save credentials**.

## 3. Verify

Add an SMS destination to an alert (**Alerts → Phone numbers**). KnoxCall sends a Verify code to the number; entering it stores the destination. That single round trip exercises the credential, the Verify service and the sending number. The operator console additionally has a *Test connection* button that reads the account with HTTP Basic auth.

## Things that bite

* **Both halves, or nothing.** With only the token (or only the SID) stored, the row is ignored and a self-hosted deployment falls back to the `TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN` environment variables — or to nothing.
* **No From number: credential fine, every send fails** at Twilio, not at save time.
* **No Verify service: no new SMS destinations.** Every number must be proven with a Verify code before it can receive alerts. Until a Verify service is configured the verification endpoint answers `503`, and unverified numbers are refused at the send boundary too, so alert SMS is unavailable — not degraded — without it.
* **Rotating the Auth Token invalidates the old one immediately.** Save the new value in KnoxCall in the same minute.
* **The Verify Service SID is an identifier, not a secret.** It sits next to the from-number in plain metadata and is useless without the SID and token.

## Related

* [Alerts](/monitoring/alerts) — SMS as an alert destination
* [Email](/integrations/setup/email) — the other alert transport