Twilio SMS Integration — Setup Guide

VocaLoop sends text messages (your SMS template with the project fill link) through Twilio's Programmable Messaging API. This guide takes you from a new Twilio account to a delivered test message.

Looking for WhatsApp instead? See the WhatsApp integration guide (VocaLoop uses Meta's Cloud API for WhatsApp, not Twilio).

What you'll end up with

Three values to paste into Integrations → Text (SMS) in VocaLoop:

VocaLoop field	What it is	Looks like
Account SID	Your Twilio account identifier (public-ish)	`ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
Auth token	The secret paired with the SID	32-char hex string
From number	A Twilio phone number with SMS capability, in E.164 format	`+14155550100`

Step 1 — Create a Twilio account

Sign up at twilio.com/try-twilio.
Verify your email and your personal phone number (this number becomes your first verified recipient — trial accounts can only send to verified numbers).
In the welcome questions, pick SMS as the product you want to use.

A trial account includes free credit — enough to complete this whole guide without paying.

Step 2 — Copy the Account SID and Auth token

Open the Twilio Console.
On the dashboard's Account Info panel you'll see:
- Account SID — starts with AC
- Auth Token — click the eye icon to reveal it
Copy both.

⚠️ The Auth token grants full access to your Twilio account. Never commit it anywhere; VocaLoop stores it encrypted and shows it masked after saving.

Step 3 — Get an SMS-capable phone number

In the Console: Phone Numbers → Manage → Buy a number (trial accounts: the dashboard also offers Get a trial phone number — one is free).
Filter by your country and make sure the SMS capability box is checked on the number you pick.
Buy/claim it, then copy the number in E.164 format — + followed by country code and number, no spaces or dashes (e.g. +14155550100).

Country-specific notes:

United States: long-code numbers require A2P 10DLC registration (Messaging → Regulatory compliance) before they can send at production volume. Trial testing to your own verified number works without it, but register before going live or carriers will filter your messages.
India and some other countries: local regulations restrict long-code sending (DLT registration in India). A US/international Twilio number can usually still deliver to these countries once geo-permissions are enabled (Step 4).

Step 4 — Enable destination countries (geo permissions)

Twilio blocks SMS to most countries by default to prevent toll fraud.

Console → Messaging → Settings → Geo permissions.
Enable every country you plan to send project links to (e.g. India, US, UK).
Save.

Skipping this is the most common cause of error 21408 ("Permission to send an SMS has not been enabled for the region").

Step 5 — Configure VocaLoop

Log in to VocaLoop and open Settings → Integrations (Settings in the left sidebar, or go to /settings/integrations).
On the Text (SMS) card, fill in:
- Account SID — from Step 2
- Auth token — from Step 2
- From number — your Twilio number in E.164 format from Step 3
Click Save. The card shows a green Configured badge.

The Auth token is encrypted at rest and shown masked (••••abcd) from now on. When editing the card later, leave the masked token untouched to keep the stored one — only paste a new value when rotating it.

Step 6 — Verify with a test send

In VocaLoop, open a project → Templates → Text, write and save a template.
Use the test send with your own mobile number in E.164 format (e.g. +919876543210).
The SMS should arrive within seconds. On a trial account it will be prefixed with "Sent from your Twilio trial account" — that disappears once you upgrade.

If the send fails, VocaLoop surfaces Twilio's error message — look it up in the table below. You can also see every attempt (with status and error codes) in the Console under Monitor → Logs → Messaging.

Trial account limitations

Limitation	Effect	Remove it by
Verified recipients only	Sends to unverified numbers fail with error `21608`	Upgrading (adding a payment method), or verifying each recipient under Phone Numbers → Verified caller IDs
Trial message prefix	Every SMS starts with "Sent from your Twilio trial account"	Upgrading
One trial number	Only a single From number	Upgrading, then buy more numbers

Troubleshooting

Twilio error	Cause	Fix
`20003` Authentication Error	Wrong Account SID / Auth token pair	Re-copy both from the Console dashboard and re-save the card
`21608` The number … is unverified	Trial account sending to an unverified number	Verify the recipient or upgrade the account
`21211` Invalid 'To' phone number	Malformed recipient	Use E.164: `+` country code + number, digits only
`21606` 'From' number not SMS-capable / not owned	From number isn't yours or can't send SMS	Use a number listed under Phone Numbers → Manage → Active numbers with the SMS capability
`21408` Permission not enabled for region	Destination country disabled	Enable it under Messaging → Settings → Geo permissions (Step 4)
`30034` / carrier filtering (US)	Unregistered A2P 10DLC traffic	Complete A2P 10DLC registration (Step 3 note)
VocaLoop says "integration not configured"	Text (SMS) card not saved for your account	Save the card on `/settings/integrations`
VocaLoop rejects the From number on save	Field expects `+` and 7–15 digits only	Remove spaces, dashes, and parentheses

Security notes

Treat the Auth token like a password. VocaLoop encrypts it at rest (Fernet, ENCRYPTION_KEY in the root .env) and masks it in every API response.
Self-hosting: set a real ENCRYPTION_KEY in .env before saving integrations. If you rotate that key, saved configs can no longer be decrypted and must be re-entered.
For tighter scoping, Twilio supports API keys (Account → API keys) as an alternative to the master Auth token; VocaLoop's card takes the Account SID + Auth token pair, so if you rotate the Auth token in Twilio, update it here too.

WhatsApp Setup

External API