Send a Text Message

Send free-form text, with an optional clickable link preview, and understand the queued response.

Last updated 05 Aug 2026

Endpoint

POST /messages.php

Requires the Authorization: Bearer header described in Authentication.

Request body

Field	Type	Required	Description
`to`	string	yes	Recipient's phone number. Digits only after stripping non-digit characters, 8-15 digits, international format without a leading `+` (for example `919876543210`).
`type`	string	yes	Must be `"text"`.
`text.body`	string	yes	The message text, 1-4096 characters.
`text.preview_url`	boolean	no	Show a link preview card if `body` contains a URL. Defaults to `false`. Can also be passed as a top-level `preview_url` field.

Example request

curl -X POST "https://riffrechat.com/api/v1/messages.php" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "text",
    "text": {
      "body": "Your order has shipped! Track it here: https://example.com/track/1042",
      "preview_url": true
    }
  }'

Success response

202 Accepted:

{
  "queue_id": "b6f1a2b0-2e2a-4a3f-9a9a-3c4f5a6b7c8d",
  "status": 0,
  "status_label": "pending",
  "source": "api",
  "charged": 0.10,
  "currency": "INR",
  "balance_after": 99.90,
  "message_id": 12345,
  "internal_queue_id": 987
}

See Message Status & Response Codes for what status and status_label mean, and how a message's status changes after it is queued.

Errors specific to this message type

`error` slug	Cause
`text_body_must_contain_between_1_and_4096_characters`	`text.body` is empty or too long.
`recipient_must_use_international_format`	`to` is missing, or is not 8-15 digits after stripping non-digit characters.

For the full error shape and general status codes, see Errors.