# Text messages

Queue a text message using a connected session and a per-message idempotency key.

## 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.







```shell
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_id` (UUID, required): Your TurbineWhats.app session ID, not an internal gateway identifier.
- `to` (string · 7–15 digits, required): 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.
- `body` (string · 1–4,096 characters, required): 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.







```json
{
  "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.











[Delivery states](https://turbinewhats.app/docs/delivery)
[Allowances and windows](https://turbinewhats.app/docs/limits)