Save 44% with yearly billing.View Plans
textbee Logotextbee.dev
Documentation

FAQ

Answers to common questions about textbee.dev: setup, sending and receiving SMS, devices, webhooks, plans and limits, self-hosting and troubleshooting.

Updated

This page answers the most common questions about textbee. Each answer is short and links to the page with the full detail. If your question is about a message that does not send or a phone that goes offline, start at Troubleshooting.

General Questions

What is textbee.dev?

textbee.dev is an open-source SMS gateway. It turns your Android phone into an SMS API. Your application calls the REST API, and the phone sends the message with its own SIM and your existing mobile plan. See the overview for how the parts fit together.

How does textbee.dev work?

  1. Install the textbee.dev Android app on your device.
  2. Register your device with your textbee.dev account.
  3. Use the REST API to send SMS messages through your device.
  4. Receive SMS messages sent to your device's phone number.

Is textbee.dev free?

Yes. The Free plan has no cost and needs no credit card:

  • 1 active device
  • 50 messages per day
  • 300 messages per month
  • Basic features

See Pricing for the paid plans.

What devices are supported?

textbee.dev works with Android devices running Android 7.0 (Nougat) or higher. iOS is not supported.

Do I need a special mobile plan?

No. textbee uses your plan's SMS allowance, so there are no per-message fees from a third-party provider. Your carrier's normal SMS rules and fair-use terms still apply.

Does textbee support MMS?

No. textbee sends and receives SMS only. It does not send or receive MMS (pictures, video or group messages).

Setup & Installation

How do I get started?

  1. Create an account at textbee.dev.
  2. Download and install the Android app from textbee.dev/download.
  3. Register your device.
  4. Start sending SMS via the API.

See the getting started guide for detailed instructions.

How do I register my device?

You can register your device with:

  • QR code (recommended): scan a QR code from your dashboard.
  • API key: paste an API key in the app.

See the device registration guide for details.

Can I use multiple devices?

Yes. The number of active devices depends on your plan:

  • Free: 1 device
  • Pro: up to 5 devices
  • Scale: up to 15 devices
  • Custom: unlimited devices

When you send without a deviceId, textbee uses your default device, or else the enabled device with the most recent heartbeat. See Devices to list your phones and set a default.

What permissions does the app need?

The app asks for:

  • SMS permissions: Send SMS to send, Receive SMS to forward incoming messages.
  • Phone state: to read the SIM cards in the phone.
  • Notifications (Android 13 and higher): to show that the gateway is running.
  • Internet: to talk to the textbee API.

On Android 15 and newer, allow restricted settings first (App info > menu > Allow restricted settings), or the SMS switch stays locked. See Messages not sending.

Android can also pause the app in the background. Set battery usage to Unrestricted. The app's Device health screen checks each item. See Keep the phone online.

Where do I find my device ID?

Open the app and go to Settings. The Device ID row shows it. You can also copy it from the Devices panel in the dashboard, or read the _id field from GET /gateway/devices. Most calls do not need it. See Devices.

Can I self-host textbee?

Yes. The API, the dashboard and the Android app are open source. You run them on your own server with MongoDB, Redis and your own Firebase project, and you build the app for your domain. See Self-hosting textbee.

Usage & Features

How do I send SMS messages?

Call POST /gateway/send-sms with your API key. See the sending SMS guide for code examples.

Can I send bulk SMS?

Yes. You can send messages to many recipients at once. See the bulk SMS guide for details.

Your phone sends the messages one at a time, with the Send Delay from the app between each one. A large batch arrives steadily, not all at once. Your bulk send limit is shown on the billing page in your dashboard.

Can I choose which SIM sends on a dual-SIM phone?

Yes. Pass simSubscriptionId in the send request. The value comes from the device's simInfo, or from the SIM Cards list in the app's dashboard tab. Without it, the phone uses the Default SIM from the app settings. The ID can change when a SIM is removed and reinserted or swapped, so check it in the app after any SIM change. See Choosing a SIM.

How do I receive SMS messages?

  1. Turn on Receive SMS in the app settings.
  2. Get messages by webhook, or read them from GET /gateway/messages.

See the receiving SMS guide and message history.

Can I filter which incoming SMS textbee forwards?

Yes. In the app, open Settings > Configure Filters. An allow list forwards only messages that match a rule. A block list drops messages that match a rule. Filters run on the phone, so a blocked message never reaches textbee. See SMS filters.

What are webhooks?

A webhook is a URL on your server. textbee sends an HTTP POST to it when an SMS event happens (message received, sent, delivered or failed). See the webhooks guide for setup, and webhook events for each payload.

Does textbee retry a failed webhook?

Yes, for some failures. A 5xx response, a timeout or a network error gets up to 10 attempts. Retries stop 30 days after the event. A 4xx response is not retried: the delivery fails after one attempt. Every retry of one delivery carries the same idempotencyKey, so your handler can skip duplicates. A subscription that keeps failing is paused, and you get an email. See Webhooks.

Can I schedule messages?

Yes. Pass a scheduledAt timestamp (ISO 8601 with a timezone, up to 72 hours ahead) when you send via the API or the SDK. The time must be in the future. There is no cancel endpoint, so check the time before you send. See Scheduled messages.

Do you support message templates?

Bulk sends from the dashboard support personalization with {{ variable }} templates. Upload a CSV and reference its columns in your message. Reusable saved templates are coming soon.

What does the delivery status of a message mean?

Each sent message has a status. pending means textbee has the message and the phone has not sent it yet. sent means the carrier accepted it. delivered means the carrier sent back a delivery report. failed means the phone or the carrier rejected it, with a numeric errorCode and an errorMessage in words. Many carriers do not send delivery reports, so a message can stay sent forever. See Delivery status.

Why is my message stuck in "pending"?

pending means the phone has not sent the message yet. The usual causes are:

  • The phone is asleep or Android paused the app.
  • The phone is working through a large batch with a Send Delay between messages.
  • The message is scheduled, and its dispatchDueAt is in the future.

See Messages not sending.

Pricing & Limits

What are the message limits?

Free plan:

  • 50 messages per day
  • 300 messages per month

Pro plan:

  • Unlimited daily messages
  • 5,000 messages per month

Scale plan:

  • Unlimited daily messages
  • 25,000 messages per month

Custom plan:

  • Custom limits based on your needs

Sent and received messages both count toward the limits. See Pricing.

What happens if I exceed my limits?

The API rejects the send with HTTP 429. The response body says which limit you reached: daily, monthly or per batch. Nothing is sent and nothing is queued. You also get an email. Upgrade your plan or wait for the limit to reset. See Messages not sending.

Can I upgrade or downgrade my plan?

Yes. You can change your plan at any time from your dashboard.

Do unused messages roll over?

No. The daily limit resets once a day. The monthly limit resets once a month, on the day your billing period started (the signup day on the Free plan, the plan start day on a paid plan). The dashboard shows the exact reset date.

Is there a free trial?

The Free plan is always free, with no credit card required.

What's your refund policy?

New Pro and Scale subscriptions have a 7-day money-back guarantee. Contact support@textbee.dev.

Technical Questions

What programming languages are supported?

textbee.dev works with any programming language that can make HTTP requests. The docs have examples for:

What's the API rate limit?

The limits that matter for most integrations are your plan's daily, monthly and per-batch message limits. A very large burst of API requests in a short time can also return 429 Too Many Requests. Wait briefly and retry with backoff. See Pricing.

Do you have an API documentation?

Yes. The API reference lists every endpoint. The same spec is at textbee.dev/openapi.json.

How do I handle errors?

The API returns standard HTTP status codes:

  • 200: the API accepted the request. Acceptance is not delivery.
  • 400: bad request. Invalid parameters, no enabled device, a disabled device, an unverified email, or a failed push to the phone.
  • 401: the API key is missing, invalid or revoked.
  • 404: the device or message does not exist on your account.
  • 429: a plan limit is used up, or too many requests in a short time.
  • 500: server error. Retry later and check the status page.

A 200 does not mean the phone sent the message. Check the message status afterwards. See Messages not sending and Delivery status.

Can I test the API?

Yes. Use the Free plan to test the API with up to 300 messages per month. GET /gateway/stats is a cheap call to check that your API key works.

Troubleshooting

My device shows as disconnected

Try these steps:

  1. Check the phone's internet connection.
  2. Open the app, go to Settings > Device health and tap Send heartbeat.
  3. Set battery usage for textbee to Unrestricted and turn on the sticky notification.
  4. Check the app permissions.
  5. If nothing helps, reconnect the device.

See Keep the phone online and the reconnecting device guide.

Messages aren't sending

  1. Check that your device is enabled and online.
  2. Verify your API key is correct.
  3. Check that you haven't exceeded your message limits.
  4. Verify phone numbers are in E.164 format (for example +12015550123).
  5. Check the API response and the message errorCode.

See Messages not sending for the full diagnosis.

I'm not receiving SMS messages

  1. Make sure Receive SMS is turned on in the app.
  2. Check that your device is connected.
  3. Check your SMS filters in the app.
  4. Verify the phone number is correct.
  5. Check your mobile plan's SMS capabilities.

See Receiving SMS and SMS filters.

The app won't install

  1. Allow installation from unknown sources for your browser or file manager.
  2. Check that you have enough storage space.
  3. Download the APK again from textbee.dev/download.
  4. Make sure your device runs Android 7.0 or higher.

API requests are failing

  1. Verify your API key is correct.
  2. Use the account-level endpoints from the API reference. They do not need a device ID.
  3. Check that the base URL is https://api.textbee.dev/api/v1.
  4. Check your plan limits. A 429 body says which limit you reached.
  5. Verify the request format: JSON body, Content-Type: application/json and the x-api-key header.

Security & Privacy

Is my data secure?

All API traffic uses HTTPS. Your messages go out through your own Android device and SIM, with no third-party SMS provider in between. Treat your API key like a password: it has full access to your account.

Where are my messages stored?

textbee stores your messages on its servers, so you can read them in the dashboard and through GET /gateway/messages. Deleting a device removes its messages from history. To keep all data on your own servers, self-host textbee.

Can I revoke API keys?

Yes. You can revoke API keys at any time from your dashboard. See API keys.

Is textbee.dev open source?

Yes. The textbee.dev code is available on GitHub.

Support

How do I get help?

What's your response time?

  • Free plan: basic support (best effort)
  • Pro and Scale plans: priority support (faster response)
  • Custom plan: dedicated account manager

Do you offer custom integrations?

Yes. Custom integrations are available for Custom plan customers. The team behind textbee also takes on integration, self-hosting and automation projects. See Services or contact sales@textbee.dev.

Still have questions?

Can't find your answer? Ask in the Discord community or email support@textbee.dev.

Next steps

Previous
Pricing
Next
API reference