Appearance
SMS with Twilio
Phone numbers need SMS for sign-up, sign-in, password resets, SMS two-factor codes and security notices to accounts without an email. The platform sends them through Twilio. Plan about 20 minutes, plus extra time if your country requires sender registration.
Choose what to set up
The site can send SMS in two ways. Most exchanges should set up both parts:
| Part | .env | Sends | Why |
|---|---|---|---|
| Verify service (recommended) | TWILIO_VERIFY_SID | All codes (sign-up, sign-in, reset, 2FA, confirmations) | Twilio creates, sends and checks the codes, translates the message, retries over other routes, and blocks SMS-pumping fraud (Fraud Guard) |
| Phone number or sender ID | TWILIO_FROM | Security notices to users without an email (password changed, email added, account closed…), and the codes too when there is no Verify service | Verify can only send codes, so other messages need a sender |
The minimum that works: Account SID + Auth Token + either TWILIO_VERIFY_SID or TWILIO_FROM. With only a Verify service, users without an email get no SMS security notices.
Create the Twilio account
- Sign up at twilio.com and verify your email and phone.
- Upgrade the account (add a payment method) before going live. Trial accounts can text only numbers you verified in the console, and every message starts with "Sent from your Twilio trial account".
- On the Console home page (Account Info), copy the Account SID (starts with
AC) and the Auth Token (click Show).
Create the Verify service
- In the Console go to Verify → Services → Create new.
- Friendly name: your exchange name. It appears in the message ("Your YourExchange verification code is: 123456"), so keep it short.
- Tick SMS as the channel and continue.
- In the service settings, keep Code length at 6. The website and app have six boxes for the code.
- Leave Fraud Guard on.
- Copy the Service SID (starts with
VA).
The site sends the user's language to Verify, so the message is in their language where Twilio supports it.
Get a sender for notices
Pick one:
- A phone number: Phone Numbers → Manage → Buy a number, with SMS capability. Use the number in international form, for example
+14155550123. - An alphanumeric sender ID (for example
YourExch, up to 11 characters): allowed in many countries but not in the US or Canada, and some countries need it pre-registered. See Messaging → Settings and Twilio's country guidelines.
Country rules
- United States: texting from ordinary (10-digit) US numbers requires A2P 10DLC registration (brand + campaign) in Messaging → Regulatory Compliance. Unregistered messages are blocked. A toll-free number needs toll-free verification instead.
- Some countries (for example India, UAE, Saudi Arabia, Turkey) require sender registration before delivery. Check Twilio's guidelines for each country you serve.
Allow your countries
To limit fraud and cost, Twilio only texts countries you allow:
- Messaging → Settings → Geo permissions: tick the countries your users are in.
- Verify → Settings (or the service's settings) → Geo permissions: same list for the Verify service.
Leave high-risk countries you don't serve unticked. SMS-pumping attacks send codes to expensive foreign numbers.
Fill in .env
ini
SMS_DRIVER=twilio
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_VERIFY_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_FROM=+14155550123bash
php artisan config:clearRestart the queue workers too (Horizon, from Market Services or php artisan horizon:terminate), because some notices are sent from background jobs.
Local testing without Twilio
SMS_DRIVER=log writes every SMS to storage/logs/laravel-YYYY-MM-DD.log (SMS to +44…: 123456 is your … code) instead of sending it. Never use it on a live site: no one would get their codes.
Built-in limits
Each number can get one code a minute and 5 codes an hour. Sign-up and reset routes are also limited per IP address. Codes are valid for 10 minutes. A code asked for one step (for example sign-up) can't be used for another (for example 2FA). Without Verify, the site keeps codes hashed and cancels a code after 5 wrong tries. With Verify, Twilio does this.
Test it
- Open
https://yourdomain.com/registerin a private window → Phone → enter your own number with the country code. - You should get the code within seconds. Enter it and finish sign-up.
- On the website (Account → Password) or in the app (Security → Password), change the password of that phone-only account. A security notice SMS should arrive (this needs
TWILIO_FROM). - In Twilio, Monitor → Logs → Messaging and Verify → Logs show each message and whether it was delivered.
Common errors
Failures are written to storage/logs/laravel-YYYY-MM-DD.log:
| Log line / what you see | Cause and fix |
|---|---|
Page: SMS is not available / log: SMS code not sent: SMS is not configured | SID, token, or both TWILIO_VERIFY_SID and TWILIO_FROM are missing. Fill them in and config:clear. |
Twilio Verify send failed: 401 … / Twilio SMS failed: 401 … | Wrong Account SID or Auth Token (did you rotate the token?). |
… 404 … The requested resource … was not found | Wrong TWILIO_VERIFY_SID (it must start with VA and belong to this account). |
… 21408 / 60605 (permission to send to this region) | The country isn't ticked in Geo permissions. |
… 21608 (unverified number) | Trial account: upgrade it, or add the number as a verified caller ID. |
… 21606 / 21659 (From number not valid) | TWILIO_FROM isn't an SMS-capable number on this account, or the country doesn't allow that sender. |
| Code arrives but is refused | The user typed an old code (each new request replaces the last), waited over 10 minutes, or entered it on a different step. |
| "Please wait a minute before asking for another code." | Expected: one code per minute per number. |
Costs
Twilio charges for every Verify verification and every SMS, and the price depends on the country (see twilio.com/pricing). Set a usage alert under Billing → Usage triggers, so an attack or a bug can't run up a large bill unnoticed.
