API referenceSms

Get an SMS sent over the API

GET
/v2/sms/{id}

The key's member sees their own sends; a threaded send is also visible to whoever can see its conversation.

Authorization

ApiKey
headerAuthorizationBearer <token>

An API key from Developers → API keys: Authorization: Bearer gauge_live_… (or pulse_k_live_…).

Path Parameters

id*string

The SMS id.

Formatuuid

Header Parameters

Gauge-Version?string

A dated version. Default 2026-10-21.

Response Body

The SMS and its latest status.

application/json
  1. response
id*string
Formatuuid
status*string

queued when the carrier accepted it; then sent, delivered, undelivered or failed as receipts arrive (sms.status_updated).

Value in"queued""sent""delivered""undelivered""failed"
to*string
from*string
numberId*string
Formatuuid
contactId*|
Formatuuid
inbox*boolean
transactional*boolean
conversationId*|

Set for an inbox: true send.

Formatuuid
messageId*|

Set for an inbox: true send.

Formatuuid
text*string
encoding*string

gsm7 (160 characters per single segment) or ucs2 (70), chosen from the text.

Value in"gsm7""ucs2"
segments*integer
Range1 <= value
estimateCents*integer

The estimate reserved before sending (segments × the rate for the destination).

Range0 <= value
costCents*|

What was charged, once the carrier accepted the message.

Range0 <= value
error*|null
createdAt*string
updatedAt*string
Example Request
curl -X GET 'https://app.gauge.chat/api/v2/sms/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "to": "string",  "from": "string",  "numberId": "4960e75f-5738-4a19-bb92-2459f0660f6c",  "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d",  "inbox": true,  "transactional": true,  "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a",  "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",  "text": "string",  "encoding": "gsm7",  "segments": 1,  "estimateCents": 0,  "costCents": 0,  "error": {    "code": "string",    "reason": "string"  },  "createdAt": "string",  "updatedAt": "string"}

Send a message POST

Text, an approved template, buttons / a list, or a file (`mediaId`) on a connection, to a thread, a contact or a new recipient. 201 when the channel sent it now; 202 with `status: queued` when it is dispatched in the background (watch `message.status_updated`). Outside WhatsApp’s 24-hour window only a template may be sent (422 `unsupported_channel_action`, reason `outside_24h_window`). On WhatsApp Cloud a template sent with `to` or `contactId` starts the conversation (contact and thread created or reused); free text to someone with no conversation is 422 `outside_24h_window`. A template must be approved, in the given language and given exactly its variables (422, reason `template_not_approved` / `template_language_not_found` / `template_variable_mismatch`). A template with a header or buttons takes `template.header` (text, image, video, document or location; media by `mediaId` or a public https `link`) and `template.buttons` (by index: quick reply `payload`, dynamic URL suffix `text`, copy code `text`, flow `payload`), checked against the template (422, reason `template_header_required` / `template_header_mismatch` / `template_button_not_found` / `template_button_mismatch` / `template_button_parameter_required`). WhatsApp Web numbers have warm-up caps (429, reason `whatsapp_web_daily_cap` / `whatsapp_web_minute_cap`) and every response carries `warnings: ["whatsapp_web_unofficial"]`. The Idempotency-Key also de-duplicates the send itself, beyond the 24-hour replay window.

Send an SMS POST

Sends a text from one of your numbers. Needs the `sms-send` scope, granted only by name (full access never includes it). Before anything is sent Gauge checks, in order: the do-not-contact list, the recipient's consent for this purpose (`transactional: true` is utility, otherwise marketing, which needs a recorded opt-in for SMS: `consent_required` otherwise), and quiet hours where the recipient is. Then it reserves the estimated cost (segments × the destination rate) against your balance and this key's daily spend cap. Any refusal sends nothing and charges nothing. On carrier acceptance the actual cost is charged and the rest released. `inbox: false` (the default) keeps the message out of the inbox; `inbox: true` threads it into the contact's SMS conversation. The response carries the encoding, segment count and the estimate. Follow delivery with `sms.status_updated`.