Skip to content
Back to search

textbee

Open-source SMS gateway. Turn your Android phone into an SMS API: send and receive SMS from your apps over REST and webhooks. Self-hostable, with a free hosted plan.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/textbee/textbee with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/textbee/textbee'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/textbee--textbee/badge.svg)](/listings/textbee--textbee)

HTML

<a href="/listings/textbee--textbee"><img src="/api/listings/textbee--textbee/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Go to [textbee.dev](https://textbee.dev) and register or login with your account 2. Install the app on your Android phone from [textbee.dev/download](https://textbee.dev/download) 3. Open the app and grant the permissions for SMS 4. Go to [textbee.dev/dashboard](https://textbee.dev/dashboard) and click register device / generate API key 5. Scan the QR code with the app or enter the API key manually 6. You're ready to send SMS from the dashboard or from your application via the REST API

Sending an SMS

Messages go out through your default device, or otherwise the enabled device with the most recent heartbeat. Pass an optional `deviceId` in the request body to send from a specific device instead. The older `/gateway/devices/{deviceId}/send-sms` route still works but is deprecated.

const API_KEY = 'YOUR_API_KEY';

await axios.post('https://api.textbee.dev/api/v1/gateway/send-sms', {
  recipients: [ '+12025550123' ],
  message: 'Hello World!',
}, {
  headers: { 'x-api-key': API_KEY },
});

<details> <summary><b>Python</b></summary>

import requests

API_KEY = 'YOUR_API_KEY'

requests.post(
    'https://api.textbee.dev/api/v1/gateway/send-sms',
    json={
        'recipients': ['+12025550123'],
        'message': 'Hello World!',
    },
    headers={'x-api-key': API_KEY},
)

</details> <details> <summary><b>curl</b></summary>

curl -X POST "https://api.textbee.dev/api/v1/gateway/send-sms" \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": [ "+12025550123" ],
    "message": "Hello World!"
  }'

</details>

Receiving SMS

Enable SMS receiving in the mobile app, then access incoming messages via the REST API, the dashboard, or webhook notifications delivered to your preferred URL. Message history is account-level: one call covers every device, no device id needed.

const API_KEY = 'YOUR_API_KEY';

await axios.get('https://api.textbee.dev/api/v1/gateway/messages?direction=received', {
  headers: { 'x-api-key': API_KEY },
});

<details> <summary><b>curl</b></summary>

curl -X GET "https://api.textbee.dev/api/v1/gateway/messages?direction=received" \
  -H "x-api-key: YOUR_API_KEY"

</details>

Use with AI agents (MCP)

The official [textbee MCP server](https://github.com/textbee/textbee-mcp) lets Claude, Cursor, and any MCP-compatible client send and read SMS through your account. Three tools: `send_sms` (send to one or many recipients), `get_messages` (read replies and verification codes, check delivery status), and `list_devices`. Plan limits apply server-side like any other send.

**claude.ai, Claude Desktop, and the Claude mobile apps** (nothing to install; the Free plan allows one custom connector):

1. In claude.ai or Claude Desktop, open **Customize**, then **Connectors**, then **+ Add** and **Add custom connector**. 2. Enter the name `textbee` and the URL `https://mcp.textbee.dev/mcp`, then click **Continue** twice. 3. Choose **Sign in now**, leave the OAuth client on the recommended option, and click **Add**. 4. Paste your API key on the textbee sign-in page and click **Connect**.

The mobile apps use connectors added on the web or desktop. On Team and Enterprise plans, an owner adds the connector for the organization first.

**Claude Code:**

# Hosted: run /mcp afterwards and choose Authenticate to sign in with your API key
claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcp

# Or local: the key stays on your machine
claude mcp add textbee -s user -e TEXTBEE_API_KEY=YOUR_API_KEY -- npx -y @textbee/mcp

**Cursor and other MCP clients** (local server, the key stays on your machine):

{
  "mcpServers": {
    "textbee": {
      "command": "npx",
      "args": ["-y", "@textbee/mcp"],
      "env": { "TEXTBEE_API_KEY": "YOUR_API_KEY" }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 636 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://textbee.dev?ref=gh-readme">
  3. <img src=".github/assets/logo.png" alt="textbee logo" width="96" height="96">
  4. </a>
  5. </p>
  6. <h1 align="center">textbee: open-source Android SMS gateway</h1>
  7. <p align="center">
  8. Turn an Android phone into an SMS API. Send and receive text messages from your apps, scripts, and AI agents over REST, webhooks, and MCP.<br>
  9. No Twilio account, no rented number, no per-message fees. Self-host it or use the free hosted plan.
  10. </p>
  11. <p align="center">
  12. <a href="https://textbee.dev?ref=gh-readme"><b>Website</b></a> ·
  13. <a href="https://textbee.dev/docs?ref=gh-readme"><b>Docs</b></a> ·
  14. <a href="https://textbee.dev/docs/api-reference?ref=gh-readme"><b>API reference</b></a> ·
  15. <a href="https://textbee.dev/download?ref=gh-readme"><b>Download the app</b></a> ·
  16. <a href="https://textbee.dev/discord"><b>Discord</b></a> ·
  17. <a href="#self-hosting"><b>Self-host</b></a>
  18. </p>
  19. <p align="center">
  20. <a href="https://github.com/textbee/textbee"><img src="https://img.shields.io/github/stars/textbee/textbee?style=flat&logo=github&color=f97316" alt="GitHub stars"></a>
  21. <a href="https://github.com/textbee/textbee/releases"><img src="https://img.shields.io/github/v/release/textbee/textbee?style=flat&color=f97316" alt="Latest release"></a>
  22. <a href="LICENSE"><img src="https://img.shields.io/github/license/textbee/textbee?style=flat" alt="AGPLv3 license"></a>
  23. <a href="https://github.com/textbee/textbee/actions/workflows/api.yaml"><img src="https://github.com/textbee/textbee/actions/workflows/api.yaml/badge.svg" alt="API build"></a>
  24. <a href="https://github.com/textbee/textbee/actions/workflows/web.yaml"><img src="https://github.com/textbee/textbee/actions/workflows/web.yaml/badge.svg" alt="Web build"></a>
  25. <a href="https://github.com/textbee/textbee/actions/workflows/android.yaml"><img src="https://github.com/textbee/textbee/actions/workflows/android.yaml/badge.svg" alt="Android build"></a>
  26. <a href="https://www.npmjs.com/package/@textbee/sdk"><img src="https://img.shields.io/npm/v/@textbee/sdk?style=flat&label=%40textbee%2Fsdk&logo=npm" alt="npm: @textbee/sdk"></a>
  27. <a href="https://pypi.org/project/textbee/"><img src="https://img.shields.io/pypi/v/textbee?style=flat&label=pypi%3A%20textbee&logo=pypi&logoColor=white" alt="PyPI: textbee"></a>
  28. <a href="https://textbee.dev/discord"><img src="https://img.shields.io/discord/1236287182940016723?style=flat&label=Discord&logo=discord&logoColor=white" alt="Discord"></a>
  29. </p>
  30. <p align="center">
  31. <a href="https://textbee.dev/dashboard?ref=gh-readme">
  32. <img src=".github/assets/dashboard-overview.png" alt="textbee web dashboard: devices, API keys, usage, and webhooks for your Android SMS gateway" width="900">
  33. </a>
  34. </p>
  35. ## What is textbee?
  36. textbee is a free, open-source **SMS gateway** that uses an Android phone and its SIM card to send and receive SMS. Your code talks to a REST API, the API pushes each message to the phone, and the phone sends it over the carrier network. Incoming messages flow back to you through the API, the web dashboard, or webhooks.
  37. It is a drop-in **Twilio alternative** for OTP codes, alerts, reminders, and two-way SMS, at the cost of your carrier plan. Over 40,000 developers and businesses use it, and the whole stack is in this repository: the NestJS API, the Next.js dashboard, and the Kotlin Android app. textbee is built and maintained by [Nuver Labs](https://nuverlabs.com/?utm_source=textbee&utm_medium=github&utm_campaign=readme), a small software studio.
  38. ## Table of contents
  39. - [Why textbee?](#why-textbee)
  40. - [Features](#features)
  41. - [Quick start](#quick-start)
  42. - [Send an SMS](#send-an-sms)
  43. - [Receive SMS](#receive-sms)
  44. - [Webhooks](#webhooks)
  45. - [Use with AI agents (MCP)](#use-with-ai-agents-mcp)
  46. - [SDKs and integrations](#sdks-and-integrations)
  47. - [Use cases](#use-cases)
  48. - [Screenshots](#screenshots)
  49. - [Stay up to date](#stay-up-to-date)
  50. - [Self-hosting](#self-hosting)
  51. - [Architecture](#architecture)
  52. - [FAQ](#faq)
  53. - [Contributing](#contributing)
  54. - [Community and support](#community-and-support)
  55. - [Who builds textbee](#who-builds-textbee)
  56. - [Security](#security)
  57. - [License](#license)
  58. ## Why textbee?
  59. | | textbee | Twilio and similar SMS APIs |
  60. |---|---|---|
  61. | **Cost per SMS** | Your carrier plan, often free or unlimited | Per-message fee plus a monthly number fee |
  62. | **Sender number** | Your own SIM. Recipients see a real local number | Rented number, often flagged as unknown |
  63. | **Setup** | About 2 minutes: install the app, scan a QR code | Account approval, compliance forms, number registration |
  64. | **Receive SMS** | Yes, on the same SIM | Yes, on the rented number |
  65. | **Self-hostable** | Yes, full control over your data | No |
  66. | **Open source** | Yes, AGPLv3 | No |
  67. | **Works with AI agents** | Yes, official MCP server | Third-party only |
  68. ## Features
  69. **Send**
  70. - Send SMS from a REST API, the web dashboard, or the official [JavaScript](https://github.com/textbee/textbee-js) and [Python](https://github.com/textbee/textbee-python) SDKs
  71. - Bulk SMS with a CSV upload, paced to stay within carrier limits
  72. - Scheduled messages up to 72 hours ahead
  73. - Multi-device and multi-SIM: pick the phone and the SIM per message
  74. - Delivery status for every message: `pending`, `dispatched`, `sent`, `delivered`, `failed`
  75. **Receive**
  76. - Receive SMS on the phone and read them from the API or dashboard
  77. - Account-level message history: one call covers every device
  78. - SMS filters on the phone: forward only the messages you need, with allow or block rules on sender and text
  79. **Integrate**
  80. - Webhooks for received messages and delivery reports, signed with HMAC-SHA256
  81. - Official [MCP server](https://github.com/textbee/textbee-mcp) for Claude, Cursor, and other AI agents
  82. - Guides for n8n, Zapier, Make, Home Assistant, Node-RED, Google Sheets, Slack, Shopify, WooCommerce, and GoHighLevel
  83. **Operate**
  84. - API keys with per-key revocation
  85. - Web dashboard for devices, usage, history, and webhooks
  86. - Self-host with Docker Compose, or use the hosted service at [textbee.dev](https://textbee.dev?ref=gh-readme)
  87. ## Quick start
  88. You need an Android phone (Android 7.0 or newer) with a SIM card. The app is distributed as an APK from [textbee.dev/download](https://textbee.dev/download?ref=gh-readme), not through the Play Store.
  89. 1. Create an account at [textbee.dev](https://textbee.dev?ref=gh-readme).
  90. 2. Install the Android app from [textbee.dev/download](https://textbee.dev/download?ref=gh-readme) and grant it the SMS permissions.
  91. 3. In the [dashboard](https://textbee.dev/dashboard?ref=gh-readme), click **Add device** and scan the QR code with the app. This creates an API key and registers the phone.
  92. 4. Send your first message from the dashboard, or from your code as shown below.
  93. That is the whole setup. The [getting started guide](https://textbee.dev/docs/getting-started?ref=gh-readme) covers each step with screenshots.
  94. If textbee saves you money or time, [star the repo](https://github.com/textbee/textbee). It helps other developers find it.
  95. ## Send an SMS
  96. One request. Messages go out through your default device, or the enabled device with the most recent heartbeat. Pass `deviceId` to pick a phone, `simSubscriptionId` to pick a SIM, or `scheduledAt` to send later.
  97. ```bash
  98. curl -X POST "https://api.textbee.dev/api/v1/gateway/send-sms" \
  99. -H "x-api-key: YOUR_API_KEY" \
  100. -H "Content-Type: application/json" \
  101. -d '{
  102. "recipients": ["+12025550123"],
  103. "message": "Your verification code is 481920. It expires in 10 minutes."
  104. }'
  105. ```
  106. <details>
  107. <summary><b>JavaScript / TypeScript</b> (official SDK)</summary>
  108. ```bash
  109. npm install @textbee/sdk
  110. ```
  111. ```js
  112. import { Textbee } from '@textbee/sdk'
  113. const textbee = new Textbee({ apiKey: process.env.TEXTBEE_API_KEY })
  114. await textbee.sendSms({
  115. recipients: ['+12025550123'],
  116. message: 'Your verification code is 481920. It expires in 10 minutes.',
  117. })
  118. ```
  119. Zero dependencies, typed, runs on Node 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge. See [textbee/textbee-js](https://github.com/textbee/textbee-js).
  120. </details>
  121. <details>
  122. <summary><b>Node.js</b> (fetch, no SDK)</summary>
  123. ```js
  124. await fetch('https://api.textbee.dev/api/v1/gateway/send-sms', {
  125. method: 'POST',
  126. headers: {
  127. 'x-api-key': process.env.TEXTBEE_API_KEY,
  128. 'Content-Type': 'application/json',
  129. },
  130. body: JSON.stringify({
  131. recipients: ['+12025550123'],
  132. message: 'Your verification code is 481920. It expires in 10 minutes.',
  133. }),
  134. })
  135. ```
  136. </details>
  137. <details>
  138. <summary><b>Python</b> (official SDK)</summary>
  139. ```bash
  140. pip install textbee
  141. ```
  142. ```python
  143. import os
  144. from textbee import Textbee
  145. textbee = Textbee(api_key=os.environ["TEXTBEE_API_KEY"])
  146. textbee.send_sms(
  147. recipients=["+12025550123"],
  148. message="Your verification code is 481920. It expires in 10 minutes.",
  149. )
  150. ```
  151. Zero dependencies, typed, runs on Python 3.9+. See [textbee/textbee-python](https://github.com/textbee/textbee-python).
  152. </details>
  153. <details>
  154. <summary><b>Python</b> (requests, no SDK)</summary>
  155. ```python
  156. import requests
  157. requests.post(
  158. "https://api.textbee.dev/api/v1/gateway/send-sms",
  159. json={
  160. "recipients": ["+12025550123"],
  161. "message": "Your verification code is 481920. It expires in 10 minutes.",
  162. },
  163. headers={"x-api-key": "YOUR_API_KEY"},
  164. )
  165. ```
  166. </details>
  167. <details>
  168. <summary><b>PHP</b></summary>
  169. ```php
  170. $ch = curl_init('https://api.textbee.dev/api/v1/gateway/send-sms');
  171. curl_setopt_array($ch, [
  172. CURLOPT_POST => true,
  173. CURLOPT_RETURNTRANSFER => true,
  174. CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY', 'Content-Type: application/json'],
  175. CURLOPT_POSTFIELDS => json_encode([
  176. 'recipients' => ['+12025550123'],
  177. 'message' => 'Your verification code is 481920. It expires in 10 minutes.',
  178. ]),
  179. ]);
  180. $response = curl_exec($ch);
  181. ```
  182. </details>
  183. <details>
  184. <summary><b>Go</b></summary>
  185. ```go
  186. body := strings.NewReader(`{"recipients":["+12025550123"],"message":"Your verification code is 481920. It expires in 10 minutes."}`)
  187. req, _ := http.NewRequest("POST", "https://api.textbee.dev/api/v1/gateway/send-sms", body)
  188. req.Header.Set("x-api-key", os.Getenv("TEXTBEE_API_KEY"))
  189. req.Header.Set("Content-Type", "application/json")
  190. resp, err := http.DefaultClient.Do(req)
  191. ```
  192. </details>
  193. Every endpoint, field, and error code is in the [API reference](https://textbee.dev/docs/api-reference?ref=gh-readme). The API also serves an interactive OpenAPI (Swagger) page at [api.textbee.dev](https://api.textbee.dev).
  194. ## Receive SMS
  195. Turn on **Receive SMS** in the Android app. Incoming messages are then available from the API, the dashboard, and webhooks. History is account-level, so one call covers every device.
  196. ```bash
  197. curl "https://api.textbee.dev/api/v1/gateway/messages?direction=received" \
  198. -H "x-api-key: YOUR_API_KEY"
  199. ```
  200. ```js
  201. const messages = await textbee.getMessages({ direction: 'received' })
  202. ```
  203. ```python
  204. messages = textbee.get_messages(direction="received")
  205. ```
  206. Read the [receiving SMS guide](https://textbee.dev/docs/receiving-sms?ref=gh-readme) for pagination, filters, and SIM details.
  207. ## Webhooks
  208. Get events on your server the moment they happen. Create a subscription in the dashboard or through the API, then handle these events:
  209. | Event | When it fires |
  210. |---|---|
  211. | `MESSAGE_RECEIVED` | The phone received an SMS |
  212. | `MESSAGE_SENT` | The carrier accepted an outgoing SMS |
  213. | `MESSAGE_DELIVERED` | The recipient's handset confirmed delivery |
  214. | `MESSAGE_FAILED` | The message could not be sent |
  215. | `SMS_STATUS_UPDATED` | Any status change on an outgoing message |
  216. Every delivery carries an `X-Signature` header: the HMAC-SHA256 of the raw body, keyed with the subscription's signing secret. Verify it before you trust the payload.
  217. ```js
  218. import { verifyWebhookSignature } from '@textbee/sdk'
  219. app.post('/webhooks/textbee', express.raw({ type: 'application/json' }), async (req, res) => {
  220. const valid = await verifyWebhookSignature({
  221. payload: req.body.toString('utf8'),
  222. signature: req.get('x-signature'),
  223. signingSecret: process.env.TEXTBEE_WEBHOOK_SECRET,
  224. })
  225. if (!valid) return res.sendStatus(401)
  226. const event = JSON.parse(req.body.toString('utf8'))
  227. res.sendStatus(200)
  228. })
  229. ```
  230. <details>
  231. <summary><b>Python</b> (Flask)</summary>
  232. ```python
  233. import json
  234. import os
  235. from flask import Flask, request
  236. from textbee import verify_webhook_signature
  237. app = Flask(__name__)
  238. @app.post("/webhooks/textbee")
  239. def textbee_webhook():
  240. valid = verify_webhook_signature(
  241. payload=request.get_data(),
  242. signature=request.headers.get("X-Signature"),
  243. signing_secret=os.environ["TEXTBEE_WEBHOOK_SECRET"],
  244. )
  245. if not valid:
  246. return "", 401
  247. event = json.loads(request.get_data())
  248. return "", 200
  249. ```
  250. </details>
  251. Retries, pauses, and the full payload shape are in the [webhooks docs](https://textbee.dev/docs/webhooks?ref=gh-readme).
  252. ## Use with AI agents (MCP)
  253. The official [textbee MCP server](https://github.com/textbee/textbee-mcp) gives Claude, Cursor, and any MCP-compatible client a phone number. Three tools: `send_sms` (one or many recipients), `get_messages` (read replies and verification codes, check delivery status), and `list_devices`. Plan limits apply server-side like any other send.
  254. **claude.ai, Claude Desktop, and the Claude mobile apps** (nothing to install; the Free plan allows one custom connector):
  255. 1. In claude.ai or Claude Desktop, open **Customize**, then **Connectors**, then **+ Add** and **Add custom connector**.
  256. 2. Enter the name `textbee` and the URL `https://mcp.textbee.dev/mcp`, then click **Continue** twice.
  257. 3. Choose **Sign in now**, leave the OAuth client on the recommended option, and click **Add**.
  258. 4. Paste your API key on the textbee sign-in page and click **Connect**.
  259. The mobile apps use connectors added on the web or desktop. On Team and Enterprise plans, an owner adds the connector for the organization first.
  260. **Claude Code:**
  261. ```bash
  262. # Hosted: run /mcp afterwards and choose Authenticate to sign in with your API key
  263. claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcp
  264. # Or local: the key stays on your machine
  265. claude mcp add textbee -s user -e TEXTBEE_API_KEY=YOUR_API_KEY -- npx -y @textbee/mcp
  266. ```
  267. **Cursor and other MCP clients** (local server, the key stays on your machine):
  268. ```json
  269. {
  270. "mcpServers": {
  271. "textbee": {
  272. "command": "npx",
  273. "args": ["-y", "@textbee/mcp"],
  274. "env": { "TEXTBEE_API_KEY": "YOUR_API_KEY" }
  275. }
  276. }
  277. }
  278. ```
  279. With the hosted connector, textbee checks your key and does not store it. Self-hosted instances use the local server with `TEXTBEE_BASE_URL`. Full setup at [textbee.dev/mcp](https://textbee.dev/mcp?ref=gh-readme) and the [MCP docs](https://textbee.dev/docs/agents/mcp?ref=gh-readme).
  280. ## SDKs and integrations
  281. | | What it is | Where |
  282. |---|---|---|
  283. | **JavaScript SDK** | `@textbee/sdk`: typed client, message iteration, webhook verification, segment counting | [textbee/textbee-js](https://github.com/textbee/textbee-js) · [npm](https://www.npmjs.com/package/@textbee/sdk) |
  284. | **Python SDK** | `textbee`: the same client for Python 3.9+, with zero dependencies | [textbee/textbee-python](https://github.com/textbee/textbee-python) · [PyPI](https://pypi.org/project/textbee/) |
  285. | **MCP server** | `@textbee/mcp`: send and read SMS from any MCP client, hosted or local | [textbee/textbee-mcp](https://github.com/textbee/textbee-mcp) · [npm](https://www.npmjs.com/package/@textbee/mcp) |
  286. | **REST API** | Any language with an HTTP client | [API reference](https://textbee.dev/docs/api-reference?ref=gh-readme) |
  287. Step-by-step guides for no-code and automation tools:
  288. [n8n](https://textbee.dev/integrations/n8n?ref=gh-readme) · [Zapier](https://textbee.dev/integrations/zapier?ref=gh-readme) · [Make](https://textbee.dev/integrations/make?ref=gh-readme) · [Home Assistant](https://textbee.dev/integrations/home-assistant?ref=gh-readme) · [Node-RED](https://textbee.dev/integrations/node-red?ref=gh-readme) · [Google Sheets](https://textbee.dev/integrations/google-sheets?ref=gh-readme) · [Slack](https://textbee.dev/integrations/slack?ref=gh-readme) · [Shopify](https://textbee.dev/integrations/shopify?ref=gh-readme) · [WooCommerce](https://textbee.dev/integrations/woocommerce?ref=gh-readme) · [GoHighLevel](https://textbee.dev/integrations/gohighlevel?ref=gh-readme)
  289. ## Use cases
  290. - **OTP and 2FA codes**: verification SMS from a local number your users recognize
  291. - **Order and appointment notifications**: confirmations, reminders, and shipping updates from your own number
  292. - **Alerts and monitoring**: server, cron, uptime, and home automation alerts that reach you even when push notifications do not
  293. - **Two-way SMS**: reply handling, keyword opt-ins, and support conversations through webhooks
  294. - **Lead follow-up and form-to-SMS**: text back a lead the moment a form is submitted
  295. - **Bulk announcements**: CSV upload to a contact list, paced to respect carrier limits
  296. - **AI agents**: let an agent send a text and read the reply
  297. ## Screenshots
  298. <details>
  299. <summary><b>Web dashboard and Android app</b></summary>
  300. <p align="center">
  301. <img src=".github/assets/send-sms.png" alt="Send SMS from the textbee web dashboard" width="800">
  302. </p>
  303. <p align="center">
  304. <img src=".github/assets/message-history.png" alt="SMS message history across all devices" width="800">
  305. </p>
  306. <p align="center">
  307. <img src=".github/assets/bulk-send.png" alt="Bulk SMS send from a CSV file" width="800">
  308. </p>
  309. <p align="center">
  310. <img src=".github/assets/webhooks.png" alt="Webhook subscriptions for incoming SMS and delivery reports" width="800">
  311. </p>
  312. <p align="center">
  313. <img src=".github/assets/app-dashboard.png" alt="textbee Android app dashboard" width="300">
  314. </p>
  315. </details>
  316. ## Stay up to date
  317. textbee ships new features and fixes every few weeks across the API, the dashboard, and the Android app.
  318. - **[Changelog](https://textbee.dev/changelog?ref=gh-readme)**: every user-facing change, newest first. Check it before you update the Android app or when an API field looks new.
  319. - **[Blog](https://textbee.dev/blog?ref=gh-readme)**: guides and tutorials on SMS automation, OTP delivery, webhooks, self-hosting, and connecting textbee to tools like n8n, Zapier, and Home Assistant.
  320. - **[GitHub releases](https://github.com/textbee/textbee/releases)**: tagged versions of this repository. Watch the repo to get notified.
  321. ## Self-hosting
  322. textbee is fully self-hostable. You run the API, the web dashboard, MongoDB, and Redis. You create a Firebase project for push messages, and you build the Android app for your own domain. All messages and account data stay in your database.
  323. The complete guide, with every environment variable explained, is at [textbee.dev/docs/self-hosting](https://textbee.dev/docs/self-hosting?ref=gh-readme). The short version is below.
  324. ### What you need
  325. - A server with Docker, or with Node.js 24.15 or newer, `pnpm`, `pm2`, MongoDB, and Redis
  326. - A domain with HTTPS. The phone and your code reach the API over the internet
  327. - A [Firebase](https://firebase.google.com) project with Cloud Messaging enabled: a service account key for the API and a `google-services.json` for the Android app
  328. - An SMTP account for verification emails and notices
  329. - Android Studio or the Android SDK to build the app
  330. ### Run with Docker Compose
  331. ```bash
  332. git clone https://github.com/textbee/textbee.git
  333. cd textbee
  334. cp api/.env.example api/.env
  335. cp web/.env.example web/.env
  336. ```
  337. Fill in both `.env` files. The ones that matter first:
  338. | File | Variable | Value |
  339. |---|---|---|
  340. | `api/.env` | `MONGO_URI`, `MONGO_ROOT_USER`, `MONGO_ROOT_PASS` | Change the default user and password. The example URI already points at the `textbee-db` container |
  341. | `api/.env` | `JWT_SECRET` | A long random string |
  342. | `api/.env` | `FRONTEND_URL` | The public URL of your dashboard |
  343. | `api/.env` | `FIREBASE_*` | Fields from your Firebase service account JSON |
  344. | `api/.env` | `MAIL_*`, `ADMIN_EMAIL` | Your SMTP server |
  345. | `api/.env` | `USE_SMS_QUEUE` | `true` to run sends through the Redis queue. Scheduled messages need it |
  346. | `web/.env` | `NEXT_PUBLIC_API_BASE_URL` | Your API URL with `/api/v1` |
  347. | `web/.env` | `NEXTAUTH_SECRET`, `NEXTAUTH_URL` | A long random string and the public dashboard URL |
  348. Then start everything:
  349. ```bash
  350. docker compose up -d
  351. ```
  352. This builds the API and web images from source and starts them with MongoDB, Redis, and an optional Mongo Express admin UI. The dashboard listens on port 3000 and the API on port 3001. Stop with `docker compose down`.
  353. ### Run without Docker
  354. <details>
  355. <summary><b>API, web, and VPS setup</b></summary>
  356. **API** (`api/`):
  357. ```bash
  358. cd api
  359. cp .env.example .env # then fill it in
  360. pnpm install
  361. pnpm build
  362. pm2 start dist/main.js --name textbee-api
  363. ```
  364. **Web** (`web/`):
  365. ```bash
  366. cd web
  367. cp .env.example .env # then fill it in
  368. pnpm install
  369. pnpm build
  370. pm2 start pnpm --name textbee-web -- start
  371. ```
  372. **Reverse proxy**: put both behind HTTPS. Example [Caddy](https://caddyserver.com) config:
  373. ```
  374. sms.example.com {
  375. reverse_proxy /api/* localhost:3001
  376. reverse_proxy /* localhost:3000
  377. }
  378. ```
  379. MongoDB can run on the same server or on [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). Redis runs the send queue and background jobs; point `REDIS_URL` at it.
  380. </details>
  381. ### Build the Android app
  382. The app must point at your domain and your Firebase project.
  383. 1. Place your `google-services.json` in `android/app/`.
  384. 2. Replace every occurrence of `textbee.dev` in the Android project with your own domain.
  385. 3. Build:
  386. ```bash
  387. cd android
  388. ./gradlew assembleRelease
  389. ```
  390. Install the APK on the phone, then register it from your dashboard the same way as on the hosted service.
  391. ## Architecture
  392. textbee has three parts: the API, the Android app, and the web dashboard. Your code never talks to the phone directly. It calls the API, and the API uses Firebase Cloud Messaging to push each message to the phone, which sends it over the carrier network through its own SIM.
  393. <p align="center">
  394. <img src=".github/assets/architecture.png" alt="textbee architecture: your app calls the textbee API, which pushes messages to the Android app over Firebase Cloud Messaging; the phone sends the SMS over the carrier network and reports status back; webhooks deliver events to your server" width="900">
  395. </p>
  396. How a message flows:
  397. 1. **Your app sends a request** to the REST API, through the JavaScript or Python SDK, or from an AI agent over MCP. The API checks the API key and plan limits, stores the message as `pending`, and picks the device.
  398. 2. **The API queues the send and pushes it to the phone** with Firebase Cloud Messaging. The queue runs on Redis and Bull. Bulk and scheduled sends wait there and are released in paced waves.
  399. 3. **The Android app sends the SMS** over the carrier network from the SIM you chose and reports back each state change: `dispatched`, `sent`, `delivered`, or `failed`.
  400. 4. **Incoming SMS go the other way.** The phone receives a message, the app uploads it to the API, and it appears in your message history.
  401. 5. **Webhooks notify your server.** The API forwards received SMS and SMS status updates to your webhook endpoint. Every delivery is signed with HMAC-SHA256 so you can verify it came from textbee.
  402. The web dashboard is a Next.js app that calls the same API your code does. It is where you register devices, create API keys, send and read messages, and manage webhooks.
  403. | Directory | What it is | Stack |
  404. |---|---|---|
  405. | [`api/`](api) | REST API, device registration, send queue, webhooks, billing | NestJS, MongoDB, Redis (BullMQ), Firebase Cloud Messaging |
  406. | [`web/`](web) | Dashboard: devices, API keys, messaging, history, webhooks | Next.js, React, Tailwind CSS |
  407. | [`android/`](android) | The gateway app: sends and receives SMS, reports status | Kotlin, Jetpack Compose, WorkManager |
  408. | [`docker-compose.yaml`](docker-compose.yaml) | One-command self-hosted stack | Docker |
  409. ## FAQ
  410. <details>
  411. <summary><b>Does my phone need to stay on?</b></summary>
  412. Yes. Messages are sent through the phone, so it needs power, the app, and an internet connection. A spare Android phone on a charger works well as a dedicated gateway. The [keep the phone online guide](https://textbee.dev/docs/troubleshooting/keep-the-phone-online?ref=gh-readme) lists the battery and background settings to change.
  413. </details>
  414. <details>
  415. <summary><b>Will my carrier block my number for sending too many messages?</b></summary>
  416. Carriers apply their own rate limits and anti-spam rules, which vary by country and plan. Personal and low-volume use is rarely a problem. For higher volume, spread sends across several devices or SIMs and keep rates reasonable. You are responsible for staying within your carrier's terms.
  417. </details>
  418. <details>
  419. <summary><b>Is it legal to send marketing SMS this way?</b></summary>
  420. SMS marketing is regulated in most countries. textbee is a tool. You are responsible for getting consent and following the laws that apply to you and your recipients.
  421. </details>
  422. <details>
  423. <summary><b>Can I use more than one phone or SIM?</b></summary>
  424. Yes. Register as many devices as your plan allows and pass `deviceId` to choose the phone. On dual-SIM phones, pass `simSubscriptionId` to choose the SIM. See [choosing a SIM](https://textbee.dev/docs/sending-sms/choosing-a-sim?ref=gh-readme).
  425. </details>
  426. <details>
  427. <summary><b>Is the app on the Play Store?</b></summary>
  428. No. Download the APK from [textbee.dev/download](https://textbee.dev/download?ref=gh-readme). The app needs SMS permissions that the Play Store restricts for this kind of app.
  429. </details>
  430. <details>
  431. <summary><b>What does the hosted service cost?</b></summary>
  432. There is a free plan, and paid plans with higher limits and more devices. See [textbee.dev/pricing](https://textbee.dev/pricing?ref=gh-readme). Self-hosting has no plan limits.
  433. </details>
  434. <details>
  435. <summary><b>Does it work on iPhone?</b></summary>
  436. No. iOS does not let apps send or read SMS on your behalf. The gateway app is Android only. You can still call the API from any device or platform.
  437. </details>
  438. ## Contributing
  439. Contributions are welcome: bug fixes, features, docs, and translations. Look for [good first issues](https://github.com/textbee/textbee/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [help wanted](https://github.com/textbee/textbee/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) to get started.
  440. 1. [Fork](https://github.com/textbee/textbee/fork) the repo and create a branch from `main`.
  441. 2. Make your change with a clear commit message.
  442. 3. Open a pull request against `main` and describe what changed and why.
  443. ### Run it locally
  444. ```bash
  445. # API (needs MongoDB; the Docker Compose file starts one)
  446. cd api && cp .env.example .env && pnpm install && pnpm start:dev
  447. # Web dashboard
  448. cd web && cp .env.example .env && pnpm install && pnpm dev
  449. # Tests
  450. cd api && pnpm test
  451. cd web && pnpm test
  452. ```
  453. Open the Android project in Android Studio from the `android/` folder. It has `dev` and `prod` build variants, described in [android/BUILD_VARIANTS_SETUP.md](android/BUILD_VARIANTS_SETUP.md).
  454. ## Community and support
  455. - [Discord](https://textbee.dev/discord): questions, help, and announcements
  456. - [GitHub issues](https://github.com/textbee/textbee/issues/new): bug reports and feature requests
  457. - [Docs](https://textbee.dev/docs?ref=gh-readme) and [FAQ](https://textbee.dev/docs/faq?ref=gh-readme)
  458. - Email: [contact@textbee.dev](mailto:contact@textbee.dev)
  459. ## Who builds textbee
  460. textbee is built and maintained by [Nuver Labs](https://nuverlabs.com/?utm_source=textbee&utm_medium=github&utm_campaign=readme), a small software studio that makes developer tools and AI products. The team also offers [custom development](https://textbee.dev/services?ref=gh-readme): integrations, SMS workflows, and self-hosted setups built on textbee.
  461. ## Security
  462. Do not open a public issue for a vulnerability. Email [contact@textbee.dev](mailto:contact@textbee.dev) with the details. See [SECURITY.md](SECURITY.md).
  463. ## License
  464. textbee is open source under the [GNU Affero General Public License v3.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.