gateway

Send an SMS

Sends one message to one or more recipients from a phone on your account. deviceId is optional: without it textbee uses your default device, otherwise the enabled device with the most recent heartbeat. Every recipient counts as one message against your plan.

post/api/v1/gateway/send-sms

Request

  • Base URL: https://api.textbee.dev
  • URL: https://api.textbee.dev/api/v1/gateway/send-sms
  • Auth: API key in header x-api-key

Request body

messagestring required

Text of the message. Long messages are split by the carrier.

recipientsstring[] required

Phone numbers to send to, in international format. Each recipient is billed as one message.

simSubscriptionIdnumber

SIM to send from, as subscriptionId from the device simInfo. Defaults to the device default SIM. Android can assign a new id when a SIM is removed and reinserted or swapped, so read the current id from the SIM Cards section of the textbee app before you hard-code it. An id that matches no active SIM is sent from the preferred SIM set in the textbee app, or the device default SIM.

scheduledAtstring

ISO 8601 time to send the message. Must be in the future. Omit to send now.

smsBodystring

Legacy alias for message. Used only when message is absent.

receiversstring[]

Legacy alias for recipients. Used only when recipients is absent.

deviceIdstring

Device to send from. When omitted, uses your default device, or the enabled device with the most recent heartbeat.

Example request

{
  "message": "Your appointment is confirmed for Tuesday at 10am.",
  "recipients": [
    "+12025550123",
    "+12025550124"
  ],
  "simSubscriptionId": 1,
  "scheduledAt": "2024-01-15T10:30:00Z",
  "receivers": [
    "+12025550123",
    "+12025550124"
  ]
}

Response

The send was accepted. Use smsBatchId to follow delivery. Acceptance is not delivery: the phone still has to be online.

Example response

{
  "data": {
    "message": "SMS added to queue for processing",
    "estimatedCompletionAt": "2026-08-22T14:05:00.000Z",
    "warning": {
      "code": "SMS_PERMISSION_MISSING",
      "message": "The textbee app on this phone last reported the SMS permission as off. The message fails if it is still off."
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.