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
string
required
The recipient’s phone number in E.164 format, including the country code. Example:
+5511999998888.string
required
The exact name of a Meta-approved template registered in your account. Example:
lembrete_consulta. Template names are case-sensitive.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.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.Response
A successful request returns202 Accepted with a JSON body confirming the message has been queued.
Response fields
string
required
Unique identifier for this message. Use it to query status with
GET /v1/messages/{id} or to correlate webhook events.string
required
Initial delivery status. Always
QUEUED immediately after a successful request.string
required
The recipient phone number, echoed back in E.164 format.
string
required
The template name used for this message.
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.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.