Send from a specific SIM

Pick the SIM that sends each message on a dual-SIM phone with simSubscriptionId, and find the ID in the textbee app or the device API.

Updated September 28, 2026

On a phone with two SIMs, simSubscriptionId picks the SIM that sends a message. You pass it on POST /gateway/send-sms, or on each item of POST /gateway/send-bulk-sms. Without it, the phone uses the Default SIM set in the textbee app.

Why choose a SIM

Two numbers. Send support messages from one number and alerts from the other.
Two carriers. Send through the carrier that has the better rate or coverage for a recipient.
Split the load. Share a large volume between two SIMs so neither one sends too fast.

Find the subscription ID

Android gives each SIM a subscription ID. It is a small number, and it is not the slot number. Find it in the app or in the API.

In the app

Open the textbee app and go to the Dashboard tab. The SIM Cards section lists each SIM with its slot and carrier, for example "SIM 1 · Example Mobile", and its simSubscriptionId. Tap the copy button next to a SIM to copy the ID.

In the API

GET /gateway/devices/{id} returns the SIMs in simInfo.sims. GET /gateway/devices returns the same field for every device.

GET/api/v1/gateway/devices/{id}

Shell

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

The response, trimmed to the SIM fields:

JSON

{
  "data": {
    "_id": "664a9b8cd0e1f2a3b4c5d6e7",
    "name": "Office phone",
    "simInfo": {
      "lastUpdated": "2026-09-28T09:12:00.000Z",
      "sims": [
        {
          "subscriptionId": 1,
          "simSlotIndex": 0,
          "carrierName": "Example Mobile",
          "displayName": "Work",
          "serviceState": "IN_SERVICE",
          "signalLevel": 3
        },
        {
          "subscriptionId": 2,
          "simSlotIndex": 1,
          "carrierName": "Example Telecom",
          "displayName": "Personal",
          "serviceState": "IN_SERVICE",
          "signalLevel": 4
        }
      ]
    }
  }
}

Field	Description
`subscriptionId`	The value to pass as `simSubscriptionId`.
`simSlotIndex`	The physical slot, starting at 0.
`carrierName`	The mobile network, as Android reports it.
`displayName`	The label the phone owner gave the SIM.
`serviceState`	Whether the SIM had service at the last report: `IN_SERVICE`, `OUT_OF_SERVICE`, `EMERGENCY_ONLY`, `POWER_OFF` or `UNKNOWN`.
`signalLevel`	Signal strength from 0 (no signal) to 4.

The phone updates simInfo with its heartbeat. simInfo.lastUpdated shows when. After you insert or swap a SIM, check the ID again. A new SIM can get a new ID.

Send from a SIM

Add simSubscriptionId to the request. This example sends from the SIM with ID 2:

Shell

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": ["+12015550123"],
    "message": "Your support ticket is updated",
    "deviceId": "664a9b8cd0e1f2a3b4c5d6e7",
    "simSubscriptionId": 2
  }'

Pass deviceId together with simSubscriptionId. Subscription IDs belong to one phone, so an ID from one device means nothing on another.

Different SIMs in one bulk request

In POST /gateway/send-bulk-sms, each item in messages can have its own simSubscriptionId:

JSON

{
  "deviceId": "664a9b8cd0e1f2a3b4c5d6e7",
  "messages": [
    { "recipients": ["+12015550123"], "message": "Sent from the work SIM", "simSubscriptionId": 1 },
    { "recipients": ["+12015550124"], "message": "Sent from the second SIM", "simSubscriptionId": 2 }
  ]
}

Sending bulk SMS has the full request in curl, JavaScript and Python.

The Default SIM setting

The app has a Default SIM setting under Settings. The app shows this hint below it: "Use the simSubscriptionId field in your API requests to override this setting". The phone picks the SIM in this order:

The simSubscriptionId in the request, if that SIM is in the phone.
The Default SIM set in the app, if that SIM is in the phone.
Android's own default SIM for SMS.

Unknown IDs fall back without an error

textbee does not check simSubscriptionId against the phone. If the ID does not match a SIM in the phone, the phone ignores it and sends from the next SIM in the list above. The request still returns 200 and the message can still reach sent.

The simSubscriptionId on the stored message is the value you sent. It does not prove which SIM the phone used. To confirm the SIM:

Send a test message to a phone you own and check the sender number it shows.
Check simInfo on the device before you send, and use an ID from that list.
After a SIM swap, read simInfo again before you send.

Frequently asked questions

Is the subscription ID the same as the slot number?

No. simSlotIndex is the slot (0 or 1). subscriptionId is an ID that Android assigns to the SIM. Always send subscriptionId.

Can I receive messages on a specific SIM?

The phone forwards messages from all its SIMs. Receiving SMS explains incoming messages.

Does it work with eSIMs?

Yes. An eSIM shows in simInfo.sims with subscriptionType set to ESIM, and you choose it in the same way.