Managing devices

A device is an Android phone with the textbee app registered to your account. Each device sends and receives SMS through its own SIM cards. Use the devices endpoints to find device IDs, pick the sending phone, and check whether a phone is online and healthy.

List and inspect devices

The devices endpoint returns every phone on your account.

To read one device, use its _id:

This request lists your devices:

curl https://api.textbee.dev/api/v1/gateway/devices \
  -H "x-api-key: YOUR_API_KEY"

The response wraps an array in data. This example is trimmed to the most useful fields:

{
  "data": [
    {
      "_id": "664a9b8cd0e1f2a3b4c5d6e7",
      "name": "Office phone",
      "enabled": true,
      "isDefault": true,
      "brand": "google",
      "model": "Pixel 7",
      "osVersion": "16",
      "appVersionName": "2.8.0",
      "receiveSMSEnabled": true,
      "smsSendDelaySeconds": 3,
      "heartbeatEnabled": true,
      "heartbeatIntervalMinutes": 30,
      "lastHeartbeat": "2026-09-28T09:45:12.000Z",
      "sentSMSCount": 1832,
      "receivedSMSCount": 412,
      "batteryInfo": { "percentage": 86, "isCharging": true, "lastUpdated": "2026-09-28T09:45:12.000Z" },
      "networkInfo": { "networkType": "wifi", "lastUpdated": "2026-09-28T09:45:12.000Z" },
      "powerInfo": {
        "isIgnoringBatteryOptimizations": true,
        "isDeviceIdleMode": false,
        "isPowerSaveMode": false,
        "lastUpdated": "2026-09-28T09:45:12.000Z"
      },
      "simInfo": {
        "lastUpdated": "2026-09-28T09:45:12.000Z",
        "sims": [
          { "subscriptionId": 1, "simSlotIndex": 0, "serviceState": "IN_SERVICE", "signalLevel": 3 }
        ]
      },
      "createdAt": "2026-06-02T14:20:31.000Z",
      "updatedAt": "2026-09-28T09:45:12.000Z"
    }
  ]
}

Device fields

The device record also has brand, manufacturer, model, os, osVersion, appVersionCode, heartbeatEnabled, appVersionInfo, deviceUptimeInfo, memoryInfo, storageInfo and systemInfo (timezone and locale). The API reference describes each one.

How textbee chooses the sending device

When you send with POST /gateway/send-sms or POST /gateway/send-bulk-sms, textbee picks the device in this order:

1. The deviceId in the request, if you pass one.
2. Your default device (isDefault: true), if it is enabled.
3. The enabled device with the most recent heartbeat.

A malformed deviceId returns 400, and an ID that is not on your account returns 404. textbee does not fall back to another phone, so a typo never sends from the wrong device. With no deviceId and no enabled device, the send returns 400. To pick a SIM on the chosen phone, see Choosing a SIM.

Manage devices

Some actions are in the dashboard, and some are in the app on the phone.

Delete a device only when you no longer need its history. To stop a phone for a while, disable it instead.

Disconnect on the phone or delete in the dashboard

These two actions are different:

• Disconnect Device in the app removes the credentials from the phone only. The app stops sending heartbeats. The device record, its settings and its history stay on your account. An enabled device still counts toward the active device limit.
• Delete in the dashboard removes the device record from your account. The phone cannot send or receive through textbee until you register the app again.

To connect a phone again after a disconnect, see Reconnecting an old device.

Active device limit

Each plan allows a number of active (enabled) devices. When you register or enable a device over that number, the API returns HTTP 429 with this message:

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

To fix it, disable a device you do not use, delete it, or change your plan. Pricing lists the device limit of each plan.

Use several phones

More phones give you more capacity and a backup.

• Throughput. Each phone sends at its own pace, set by its send delay and its carrier. Two phones can send about twice as many messages per minute. Split the load by passing a different deviceId per request.
• Redundancy. textbee does not move a send to another phone when the default phone is offline. Check lastHeartbeat before a send and pass the deviceId of a healthy phone.
• One phone per number. A phone with two SIMs is one device. Choose the SIM with simSubscriptionId. Use a separate phone when you need more capacity on the same number set.

Received messages from all phones appear in one history. Filter them with deviceIds. See Message history and polling.

Check phone health from the API

Read these fields from GET /gateway/devices/{id} to judge whether a phone can send now:

A heartbeat time in the future means the phone clock changed. Fix the date and time on the phone.

The app has the same checks on the phone. Open Settings > Device health: "What can slow down or stop messages on this phone, in either direction, and what to change." It lists each problem with the fix for your phone brand. The guide Keep the phone online walks through each fix.

Frequently asked questions

Where do I find a device ID?

Call GET /gateway/devices and read _id. The app also shows it under Settings > Device ID.

Can I change a device with the API?

The API reads devices. Enable, disable and rename a device in the app. Set the default device in the dashboard, or with setDefaultDevice in the JavaScript SDK.

Why is lastHeartbeat old?

The phone has not sent a heartbeat for a while. The phone is off, has no network, or Android stopped the app in the background. See Keep the phone online.

Does deleting a device delete the phone's SMS?

No. Delete removes the device and its messages from textbee only. The SMS in the phone's own inbox stay on the phone.

Next steps

• Registering a device: add a phone to your account
• Choosing a SIM: send from a specific SIM
• Keep the phone online: stop Android from pausing the app
• Messages not sending: fix stuck and failed sends
• Pricing: device limits per plan