Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Send message

/messagesPOST
Send one transactional message. Required scope: messages:write. Idempotency-Key is required. HTTP 201 acknowledges the returned provider/validation outcome; delivery is tracked separately. test=true validates without sending or charging.
Authorization
BearerAuth *Bearer <token>
API key generated under Account Settings → API Keys (rk_live_...). Send as header Authorization: Bearer <key>.
Request Bodyapplication/jsonrequired
to *string
Recipient phone number in E.164 format (e.g. +2348012345678) or email address.
Example: "+2348012345678"
message?string
Message text. Required unless template is supplied.
Example: "Your verification code is 849204."
template?string
Public ID of a saved message template (e.g. tpl_x83k29sk).
Example: "tpl_x83k29sk"
variables?object
Caller-facing template values. Convert generates provider-specific Meta component parameters internally.
channel?"email" | "whatsapp" | "sms" | "smart"
Smart uses WhatsApp or SMS, never email.
Default: "smart"
first_name?string
Optional recipient first name (persisted to contact record).
Example: "Ada"
last_name?string
Optional recipient last name.
Example: "Obi"
list_id?integer
custom_fields?object
whatsapp_opt_in?boolean
whatsapp_opt_in_source?string
Audit label describing where consent was collected.
Example: "tailora_checkout"
session?string
Specific connected WhatsApp session ID.
Example: "sess_938472"
sender?string
subject?string
html?string
test?boolean
Validate without delivery or wallet charge.
Default: false
purpose?string
Use otp for phone verification messages.
Response
201 · Message successfully queued or sent
success *boolean
Example: true
channel *"whatsapp" | "sms" | "email" | "smart"
Example: "whatsapp"
status *string
Example: "sent"
message_id *string
Example: "wamid.HBgLMjM0ODAxMjM0NTY3OAEU"
cost *number (float)
Example: 5
template?string | null
Example: "tpl_x83k29sk"
to *string
Example: "+2348012345678"
400 · Bad request (e.g. missing or invalid Idempotency-Key)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
401 · Unauthorized (missing, invalid, or revoked Bearer token)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
402 · Payment Required (insufficient wallet balance)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
409 · Conflict (Idempotency key reuse with different payload or concurrently processing)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
422 · Unprocessable Entity (validation or channel error)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
502 · Bad Gateway (upstream delivery provider rejected the send request)
success *boolean
Example: false
error *string
Human-readable error message explaining the failure reason.
Example: "Recipient not reachable on WhatsApp."
error_code *string
Stable machine-readable error code.
Example: "recipient_not_on_whatsapp"
Request example
curl -X POST "https://convert.ruut.chat/api/v1/messages" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+2348012345678",
  "message": "Your verification code is 849204.",
  "channel": "smart",
  "first_name": "Ada",
  "last_name": "Obi",
  "whatsapp_opt_in": true,
  "whatsapp_opt_in_source": "tailora_checkout"
}'
Response example
{
  "success": true,
  "channel": "whatsapp",
  "status": "sent",
  "message_id": "wamid.HBgLMjM0ODAxMjM0NTY3OAEU",
  "cost": 5,
  "to": "+2348012345678"
}