Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.relayos.com.br/llms.txt

Use this file to discover all available pages before exploring further.

The POST /v1/messages endpoint is how you send a WhatsApp message through RelayOS. Every message is built on a Meta-approved template — you select the template by name, supply your recipient’s phone number, and optionally pass dynamic variable values to personalize the content. RelayOS queues the request, delivers it via the official WhatsApp Cloud API, and gives you a message ID you can use to track delivery in real time.

​
Request parameters

​
to
string
required
The recipient’s phone number in E.164 format, including the country code. Example: +5511999998888.
​
template
string
required
The exact name of a Meta-approved template registered in your account. Example: lembrete_consulta. Template names are case-sensitive.
​
language
string
required
The BCP 47 language code for the template. Must match the language the template was approved in. Common values: pt_BR, en_US.
​
variables
object
An object mapping numbered string keys to their replacement values for template placeholders. Keys start at "1" and match the order of {{1}}, {{2}}, … in your template body. Example: {"1": "João", "2": "14h"}.

​
Send a message

The example below sends a consultation reminder with three dynamic variables filled in.
Include an Idempotency-Key header on every request to prevent duplicate messages if your client retries due to a network error. RelayOS returns the original response for any repeated key. See Use Idempotency Keys for details.
curl -X POST https://api.relayos.com.br/v1/messages \
  -H "Authorization: Bearer rly_live_xxx..." \
  -H "Idempotency-Key: pedido-42-lembrete" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999998888",
    "template": "lembrete_consulta",
    "language": "pt_BR",
    "variables": {
      "1": "João Silva",
      "2": "14h",
      "3": "Dra. Helena"
    }
  }'

​
Response

A successful request returns 202 Accepted with a JSON body confirming the message has been queued. 
{
  "id": "msg_01hwz3k8j2fxqbv9r4tp6d",
  "status": "QUEUED",
  "to": "+5511999998888",
  "template": "lembrete_consulta",
  "queuedAt": "2026-05-14T10:30:00Z"
}

​
Response fields

​
id
string
required
Unique identifier for this message. Use it to query status with GET /v1/messages/{id} or to correlate webhook events.
​
status
string
required
Initial delivery status. Always QUEUED immediately after a successful request.
​
to
string
required
The recipient phone number, echoed back in E.164 format.
​
template
string
required
The template name used for this message.
​
queuedAt
string
required
ISO 8601 timestamp of when RelayOS accepted and queued the message.

​
Message status lifecycle

After a message is queued, RelayOS advances its status as it moves through the delivery pipeline. You can track these changes in real time by configuring a webhook. 
QUEUED → SENT → DELIVERED → READ
              ↘
              FAILED
StatusMeaning
QUEUEDRelayOS accepted the request and is forwarding it to Meta.
SENTMeta confirmed the message left their servers.
DELIVEREDThe message arrived on the recipient’s device.
READThe recipient opened the message.
FAILEDAll delivery attempts failed. RelayOS retried with exponential backoff before marking it failed.
A FAILED status means all automatic retries were exhausted. Check the webhook payload for an error code from Meta, then determine whether to re-send the message.