Text messaging remains a critical channel for many applications, especially in regions where SMS is still king. But setting up reliable SMS gateways often means costly hardware or complex telecom integrations. TextBee sidesteps these hurdles by repurposing everyday Android phones as programmable SMS gateways, connected to a centralized REST API. It achieves this with a surprisingly straightforward yet effective architecture that combines native Android SMS control, a modern web backend, and Firebase Cloud Messaging (FCM) to bridge the two.
How TextBee turns Android phones into SMS gateways
TextBee’s core idea is to transform an Android phone into an SMS relay that can send and receive messages on behalf of a centralized server. The repo’s architecture centers around four main components:
Android client app: Runs on the phone, handling SMS sending and receiving using native Android SMS permissions. It listens for push commands via Firebase Cloud Messaging to send SMS and reports back status updates.
NestJS backend API: Exposes a REST API for clients to send SMS messages, query received SMS, and manage devices. It authenticates requests using API keys scoped per device.
Next.js/React dashboard: Provides a web interface for users to register devices, generate API keys, send SMS messages (individually or bulk via CSV upload), and view received messages.
MongoDB database: Stores device and message data persistently, with MongoExpress as an optional admin UI.
The Android app and backend communicate asynchronously via FCM. When a REST API client requests an SMS send, the backend pushes a command to the phone through FCM. The phone executes the send operation using native SMS APIs, then reports success or failure back to the server.
This design cleverly leverages FCM as a push-based command relay instead of building a custom persistent connection, avoiding battery drain and complex device management. The use of native SMS APIs means no rooting or custom ROMs are required, making it accessible for common consumer devices.
What makes TextBee interesting under the hood
The standout technical aspect is the use of Firebase Cloud Messaging to orchestrate SMS sending commands and status updates between the cloud and edge device. This pattern turns an ordinary Android device into a remotely programmable cellular modem without low-level device hacking.
TextBee uses a device-scoped API key authentication model, ensuring that REST API requests are securely tied to a specific physical device. This keeps the SMS gateway secure and manageable at scale.
The backend is built with NestJS, a mature TypeScript framework that enforces modularity and dependency injection, contributing to readable and maintainable code. The React/Next.js dashboard offers a clean UX for device registration and SMS management.
Supporting bulk SMS sending via CSV upload is a practical feature for real-world use cases like marketing or notifications.
The tradeoff here is reliance on Firebase Cloud Messaging and Android devices, which means availability and latency depend on Google services and device connectivity. Additionally, SMS sending throughput is limited by the Android device’s hardware and carrier constraints — this is not a high-throughput SMS gateway for large-scale telecom needs.
However, for many applications needing flexible, low-cost SMS sending with a simple REST API, this approach is elegant and pragmatic.
Getting started with TextBee
The README outlines a straightforward onboarding flow:
- Go to textbee.dev and register or login with your account
- Install the app on your Android phone from textbee.dev/download
- Open the app and grant the permissions for SMS
- Go to textbee.dev/dashboard and click register device / generate API Key
- Scan the QR code with the app or enter the API key manually
- You are ready to send SMS messages from the dashboard or from your application via the REST API
Here is an example of sending an SMS via the REST API using JavaScript and Axios:
const API_KEY = 'YOUR_API_KEY';
const DEVICE_ID = 'YOUR_DEVICE_ID';
await axios.post(`https://api.textbee.dev/api/v1/gateway/devices/${DEVICE_ID}/send-sms`, {
recipients: [ '+251912345678' ],
message: 'Hello World!',
}, {
headers: {
'x-api-key': API_KEY,
},
});
Or equivalently using curl:
curl -X POST "https://api.textbee.dev/api/v1/gateway/devices/YOUR_DEVICE_ID/send-sms" \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"recipients": [ "+251912345678" ],
"message": "Hello World!"
}'
Receiving SMS is also supported by enabling it in the mobile app, then fetching received messages via the API:
await axios.get(`https://api.textbee.dev/api/v1/gateway/devices/${DEVICE_ID}/get-received-sms`, {
headers: { 'x-api-key': API_KEY },
});
curl -X GET "https://api.textbee.dev/api/v1/gateway/devices/YOUR_DEVICE_ID/get-received-sms" \
-H "x-api-key: YOUR_API_KEY"
Self-hosting is supported through Docker Compose, allowing you to deploy MongoDB, MongoExpress, the NestJS backend, and configure Firebase credentials and domain routing through environment variables.
When TextBee makes sense and its limits
TextBee is a practical solution for developers or small teams who need to send and receive SMS messages programmatically without investing in specialized SMS gateway hardware or telecom integrations.
Its strength lies in simplicity, accessibility, and leveraging commodity Android devices you might already have. The architecture is clean, with a modern TypeScript backend and React dashboard, plus a native Android client that handles SMS reliably.
However, this approach has clear limitations. It is not designed for very high throughput or mission-critical SMS infrastructure. The dependency on Firebase Cloud Messaging means you rely on Google services and network conditions. Latency can vary depending on device availability and mobile carrier.
Security is handled reasonably well with API keys and device scoping, but exposing SMS gateways to the internet always requires caution.
In short, TextBee is ideal for proof-of-concept projects, small-scale SMS automation, or regions where SMS gateways are hard to obtain but Android devices are plentiful. It’s worth understanding even if your production needs eventually outgrow this approach.
The codebase is surprisingly clean for a multi-component system, and the repo offers a solid foundation for anyone interested in SMS automation or edge device orchestration.
Related Articles
- Novu: Open-source multi-channel notification infrastructure with a unified API — Novu offers a unified API for multi-channel notifications—email, SMS, push, chat—with an open core model balancing open
- Supabase: composable open-source backend-as-a-service built around Postgres — Supabase combines specialized open-source tools around Postgres to offer a Firebase-like backend platform. Its modular a
- Kong Gateway: A universal API gateway with advanced AI traffic routing and governance — Kong Gateway extends traditional API management with universal LLM API routing, semantic security, and AI-specific featu
- Flarum: A modular PHP forum platform built on Laravel with a clean separation of core and app — Flarum is an open-source PHP forum platform with a modular architecture, separating core features from the main app skel
- PinchTab: Token-efficient Chrome automation for AI agents with Go — PinchTab is a Go HTTP server enabling AI agents to control Chrome instances efficiently by extracting structured text, c
→ GitHub Repo: vernu/textbee ⭐ 2,563 · TypeScript