Registering a device

Connect an Android phone to your textbee account with a QR code or an API key, name it, set a default device and check its heartbeat.

Updated October 3, 2026

Registering a device links the textbee app on an Android phone to your account. You scan a QR code from the dashboard or paste an API key into the app. After registration the phone shows in your Devices list with a Device ID, and the API can send through it.

Before you start

A textbee account with a verified email.
The textbee app installed on the phone. See Setting up textbee.
The phone connected to the internet.

Option 1: Scan a QR code (recommended)

Open the dashboard. In the Devices panel, click Add a device and then Continue. The dashboard creates a new API key and shows it as a QR code. You can also click Generate API Key in the API Keys panel.
Open the textbee app on the phone and tap Get Started.
On Connect your account, tap Scan QR Code and point the camera at the QR code.
On Set up your device, enter a name (optional) and tap Register Device.
Allow the SMS permission when the app asks, then tap Continue. On Android 15 and newer, Android blocks the permission at first. Follow the note below this list.

On Android 15 and newer the SMS permission is locked for apps installed from an APK. Open App info, tap the menu (⋮), choose Allow restricted settings, then allow SMS. Step by step with screenshots.

The app shows You're all set! and the Device ID. The phone now shows in the Devices panel of the dashboard.

Option 2: Paste an API key

Use this option when you cannot scan the screen, for example when the dashboard is open on the same phone.

In the dashboard, click Generate API Key in the API Keys panel and copy the key. The dashboard shows the key only once.
Open the app, tap Get Started, then tap Enter manually instead.
Paste the key in the API Key field and tap Next.
Enter a device name (optional) and tap Register Device.
Allow the SMS permission when the app asks, then tap Continue. On Android 15 and newer, allow restricted settings first, as in the note above.

The phone keeps the API key it registered with. If you revoke that key, the phone can no longer reach textbee, and you must reconnect it with a new key.

Name the device

The Device Name (optional) field sets a label, for example "Office phone". If you leave it empty, textbee uses the brand and model of the phone. The name shows in the dashboard, in the name field of GET /gateway/devices, and on each message in the history. A clear name helps when you have more than one phone. To change it later, open Settings > Device Name in the app.

The Device ID

Each registered phone gets a Device ID. The API returns it as _id. Pass it as deviceId when you want a specific phone to send a message. You find it in three places:

On the You're all set! screen in the app.
In the Devices panel of the dashboard (the copy button next to each device).
In the response of GET /gateway/devices.

Keep the Device ID. You need it to reconnect the phone after a reinstall.

The default device

A send request without deviceId goes out from your default device. If you have not set a default, textbee uses the enabled device with the most recent heartbeat. To choose the default, open the device actions menu in the Devices panel and click Set as default. The API shows it as isDefault: true.

More than one device

One account can have several phones. Each phone registers with the same steps and gets its own Device ID. Use more than one phone to split a large volume, to send from different numbers, or to keep a backup.

Your plan sets how many devices can be active at the same time. When you reach the limit, registration fails with this error:

Active device limit reached: your plan allows up to N active device(s)... Disable or delete another device, or upgrade your plan

To free a slot, turn off Gateway Enabled in the app on a phone you do not use, or delete that device in the dashboard. You can also upgrade. The pricing page lists the device limit for each plan.

The heartbeat

The app sends a heartbeat to textbee at a fixed interval. A heartbeat is a short report that says "this phone is online". It also carries the battery level, network type, app version and SIM list.

The last one is stored as lastHeartbeat on the device. It matters for two reasons:

It shows if the phone is online. A phone that has been silent for a long time is likely offline, asleep or stopped by Android. Messages sent to it wait until it comes back.
It picks the sender. Without a default device, textbee sends from the enabled device with the most recent heartbeat.

By default the app sends one every 30 minutes. The heartbeatIntervalMinutes field on the device shows the interval. To send one now, open Settings > Device health in the app and tap Send heartbeat on the Heartbeat row. Devices explains every device field, and Keep the phone online covers phones that go silent.

Frequently asked questions

Do I register again after I reinstall the app?

No. Reconnect the phone with its existing Device ID instead. A new registration creates a new device, and the message history stays with the old one. See Reconnecting an old device.

Can one phone belong to two accounts?

No. The app on a phone holds one set of credentials at a time.

The registration failed. What do I check?

Check that the phone is online, that the API key is not revoked, and that your plan has room for another active device.