Wiki · Integrations
SMS via Twilio
SMS is the dumbest and most expensive channel — and still useful. When, how and for how much.
✉️
SMS is the dumbest and most expensive channel — and still useful.
It has no history, no formatting, and every message costs money. On the other hand it arrives where
neither WhatsApp nor Telegram will be opened: on a plain phone. Use it for notifications and short
questions, not for attachments.
What you need
| Item | Note |
|---|---|
| A Twilio account | It has a trial mode; a trial number only messages verified numbers |
| An SMS-capable number | A number bought at Twilio |
| A publicly reachable server | Twilio delivers incoming SMS to a webhook — you need an HTTPS address |
aiohttp in the environment | Installed by the dependency step for the sms extra |
Configuration
# ~/.hermes/.env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+420777123456
# who the agent may answer (always recommended)
SMS_ALLOWED_USERS=+420777654321,+420777222333
# where scheduled job results go
SMS_HOME_CHANNEL=+420777654321
# must match the URL configured at Twilio exactly
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio
hermes gateway setup # or via the wizard: pick SMS (Twilio)
The Twilio webhook
Twilio Console → Phone Numbers → Manage → Active Numbers → your number
Messaging → A MESSAGE COMES IN
Webhook: https://your-server:8080/webhooks/twilio
Method: POST
Running Hermes on a home machine? Expose the port temporarily with a tunnel
(cloudflared tunnel --url http://localhost:8080 or ngrok http 8080) and put the
same URL in both Twilio and SMS_WEBHOOK_URL. Without the match the adapter
refuses to start — protection against forged requests.
Security
| Measure | Why |
|---|---|
SMS_ALLOWED_USERS | Without it the agent answers anyone who knows your number — and sends SMS on your bill |
| Signature validation | Twilio signs requests; SMS_INSECURE_NO_SIGNATURE is for testing only |
| HTTPS only | An HTTP tunnel is an invitation for foreign requests |
| A budget | SMS is billed per message; set a cap at Twilio and watch the spend |
What it costs
Two parts: a monthly number fee and a per-message price. Twilio's price list changes — check it in the console before deploying. For comparison: Telegram and WhatsApp are free, so SMS only makes sense where nothing else works.
Things to watch
| Situation | What to do |
|---|---|
| Messages vanish on a trial account | A trial number only messages verified numbers; verify them in the console |
| The agent stays silent | SMS_WEBHOOK_URL is missing or does not match the Twilio URL |
| It answers strangers | No allowlist — add one immediately |
| A long answer falls apart | SMS has a character limit and diacritics shorten it; keep it short |