A bridge that intercepts Twilio message status callbacks and resends failed messages via the SMSGate API, providing a fallback channel without changing existing Twilio-based software. See Twilio Fallback for the full guide.
The Twilio Fallback Service listens for Twilio outbound message status callbacks, validates the X-Twilio-Signature header, and for failed or blocked messages automatically resends them through SMSGate. Applications keep using Twilio as their primary channel; SMSGate becomes the delivery fallback.
- 📖 About
- 📚 Table of Contents
- ⭐ Features
- 📦 Prerequisites
- 🚀 Getting Started
- ⚙️ Configuration
- 📦 Deployment
- 🔌 API Overview
- 📚 Documentation
- 🤝 Contributing
- 📄 License
- Twilio message status callback webhook at
/api/twilio - Twilio request signature validation
- Automatic resend of failed messages via the SMSGate API
- Health and Prometheus metrics endpoints
- Linux server with a public IP address (for Twilio webhooks)
- A Twilio account with message status callbacks enabled
- An SMSGate account
- Domain name and SSL/TLS certificate (recommended for webhook security)
make build
cp .env.example .env # fill in Twilio and SMSGate credentials
./bin/twilio-fallbackConfigure your Twilio account to send message status callbacks to https://your-host/api/twilio.
Configuration is loaded from environment variables (double-underscore nesting) or an optional YAML file. The YAML file is selected via CONFIG_PATH, which must be set in the process environment before startup — a value placed only in .env cannot select the YAML file. See .env.example.
| Variable | Default | Description |
|---|---|---|
HTTP__ADDRESS |
127.0.0.1:3000 |
HTTP listen address |
HTTP__PROXY_HEADER |
X-Forwarded-For |
Trusted proxy header |
HTTP__PROXIES |
(empty) | Comma-separated trusted proxies |
TWILIO__ACCOUNT_SID |
(required) | Twilio account SID |
TWILIO__AUTH_TOKEN |
(required) | Twilio auth token |
TWILIO__CALLBACK_URL |
(empty) | Public callback URL (defaults from Host) |
SMSGATE__BASE_URL |
https://api.sms-gate.app/3rdparty/v1 |
SMSGate API base URL |
SMSGATE__USERNAME |
(required) | SMSGate username |
SMSGATE__PASSWORD |
(required) | SMSGate password |
SMSGATE__TIMEOUT |
1s |
SMSGate API timeout |
CONFIG_PATH |
(empty) | Optional YAML config file path |
Full reference: Twilio Fallback.
docker compose up -dOr with Docker directly:
docker run -d --name twilio-fallback \
-p 3000:3000 \
--env-file .env \
-e HTTP__ADDRESS=:3000 \
ghcr.io/android-sms-gateway/twilio-fallback:latestSee compose.yaml for the full service definition.
| Method | Path | Description |
|---|---|---|
| POST | /api/twilio |
Twilio message status callback webhook |
| GET | /health |
Liveness probe |
| GET | /health/ready |
Readiness probe |
| GET | /metrics |
Prometheus metrics |
Contributions are welcome. Open an issue or pull request; follow the repo's make fmt / make lint / make test checks and the contribution guide.
Apache-2.0. See LICENSE.
This project is not affiliated with, endorsed by, or sponsored by Twilio. It is an independent project that utilizes the Twilio API. Twilio is a trademark of Twilio Inc.