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

# POST /v1/messages — Send a WhatsApp Message

> Send a transactional WhatsApp message using an approved Meta template. Pass recipient number, template name, language code, and optional variable values.

Use this endpoint to send a transactional WhatsApp message to a single recipient. The message must reference an approved Meta template — RelayOS routes the request through the official WhatsApp Cloud API and immediately returns a message ID you can use to track delivery.

## Request

**`POST https://api.relayos.com.br/v1/messages`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for your RelayOS API key. Format: `Bearer YOUR_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  An arbitrary unique string (e.g., `order-99-reminder`) that prevents duplicate sends if you retry the request due to a network error. Keys are deduplicated for 24 hours.
</ParamField>

### Body

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format, including the country code. Example: `+5511999998888`.
</ParamField>

<ParamField body="template" type="string" required>
  Name of an approved Meta WhatsApp template registered in your account. Example: `lembrete_consulta`.
</ParamField>

<ParamField body="language" type="string" required>
  BCP-47 language code matching the template variant to use. Example: `pt_BR`, `en_US`.
</ParamField>

<ParamField body="variables" type="object">
  Key-value pairs that substitute numbered placeholders in the template body. Keys are string integers starting at `"1"`.

  ```json theme={null}
  {
    "1": "João Silva",
    "2": "14h",
    "3": "Dra. Helena"
  }
  ```
</ParamField>

## Example

```bash theme={null}
curl -X POST https://api.relayos.com.br/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-99-reminder" \
  -d '{
    "to": "+5511999998888",
    "template": "lembrete_consulta",
    "language": "pt_BR",
    "variables": {
      "1": "João Silva",
      "2": "14h",
      "3": "Dra. Helena"
    }
  }'
```

## Response

A `200` response means RelayOS accepted the message and placed it in the send queue. Actual delivery to the recipient happens asynchronously.

<ResponseField name="id" type="string">
  Unique message ID assigned by RelayOS. Use this to poll status via `GET /v1/messages/{id}` or match it against webhook events.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status of the message. Always `QUEUED` on creation.
</ResponseField>

<ResponseField name="to" type="string">
  The recipient phone number as provided in the request.
</ResponseField>

<ResponseField name="template" type="string">
  The template name used for this message.
</ResponseField>

<ResponseField name="queuedAt" type="string">
  ISO 8601 timestamp of when the message was accepted into the queue. Example: `2026-05-14T10:30:00Z`.
</ResponseField>

```json theme={null}
{
  "id": "msg_01hwz3k9fxe5vr2t8qn6yc4bmd",
  "status": "QUEUED",
  "to": "+5511999998888",
  "template": "lembrete_consulta",
  "queuedAt": "2026-05-14T10:30:00Z"
}
```

<Info>
  Use `Idempotency-Key` to safely retry requests without risk of sending the same message twice. RelayOS deduplicates requests with the same key for 24 hours.
</Info>