Skip to main content

​
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: 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.
  • Alerts — SMS as an alert destination
  • Email — the other alert transport