Text messages

Send text#

POST /messages/text requires send permission, a ready session, active service access, and available allowance. Only individual phone-number recipients are supported by this send endpoint.

curl --request POST 'https://turbinewhats.app/api/v1/messages/text' \
  --header "Authorization: Bearer $TURBINEWHATS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-confirmed' \
  --data '{
  "channel_id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
  "to": "14155550123",
  "body": "Your order is confirmed."
}'

Request fields#

Unknown request properties are rejected. Send Content-Type: application/json and an Idempotency-Key of 8–100 letters, digits, hyphens, or underscores.

channel_idRequired

UUID

Your TurbineWhats.app session ID, not an internal gateway identifier.

toRequired

string · 7–15 digits

International phone number with country code. An optional leading + is normalized. On paid access, a group ID ending in @g.us is also accepted. Spaces and local-number formatting are not accepted.

bodyRequired

string · 1–4,096 characters

The text to send. Length is measured as JavaScript UTF-16 code units.

Idempotent retries#

The first accepted request reserves allowance and returns HTTP 202 with data.id, data.status, and data.replayed=false. Retrying the same request with the same key returns the original ID, current state, and replayed=true.

A key is unique across the account. Reusing it for a different session, kind, or payload returns HTTP 409 idempotency_conflict. Reuse the same payload and JSON structure for retries. Do not regenerate keys automatically after a timeout.

{
  "data": {
    "id": "b4829d81-353f-4821-ae99-77adeab896ce",
    "status": "sent",
    "replayed": true
  }
}

Trial recipients#

During the trial, text may be sent only to the connected number or to a test recipient approved by support. Request an additional recipient through the workspace; entering a number alone does not authorize it. Paid access does not permit unsolicited outreach.