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

# WhatsApp Template Messages: Setup and Usage

> Learn how to create and use approved WhatsApp message templates with RelayOS, including dynamic variable substitution and language codes.

WhatsApp templates are pre-approved message formats required by Meta for any business-initiated conversation. Before you can send a message with RelayOS, the template you reference must be approved by Meta. Once approved, you use the template name and language code in your `POST /v1/messages` request, optionally substituting numbered placeholders with dynamic values specific to each recipient.

<Note>
  Templates must be approved by Meta before you can use them in messages. Approval typically takes a few minutes for standard templates but can take up to 24 hours. You cannot send messages with a template in `PENDING` or `REJECTED` status.
</Note>

## List your templates

Use `GET /v1/templates` to see all templates in your account along with their current approval status.

```bash theme={null}
curl https://api.relayos.com.br/v1/templates \
  -H "Authorization: Bearer rly_live_xxx..."
```

A successful response returns an array of template objects:

```json theme={null}
[
  {
    "name": "lembrete_consulta",
    "language": "pt_BR",
    "status": "APPROVED",
    "components": [
      {
        "type": "BODY",
        "text": "Olá, {{1}}! Sua consulta está marcada para {{2}} com {{3}}."
      }
    ]
  },
  {
    "name": "order_confirmation",
    "language": "en_US",
    "status": "APPROVED",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order #{{2}} has been confirmed."
      }
    ]
  }
]
```

## Create a template

Use `POST /v1/templates` to submit a new template for Meta's review. Provide the template name, language, and the component structure including the message body.

```bash theme={null}
curl -X POST https://api.relayos.com.br/v1/templates \
  -H "Authorization: Bearer rly_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lembrete_consulta",
    "language": "pt_BR",
    "components": [
      {
        "type": "BODY",
        "text": "Olá, {{1}}! Sua consulta está marcada para {{2}} com {{3}}."
      }
    ]
  }'
```

The response confirms the template was submitted:

```json theme={null}
{
  "name": "lembrete_consulta",
  "language": "pt_BR",
  "status": "PENDING"
}
```

## Use templates when sending messages

Once a template is `APPROVED`, reference it by name in `POST /v1/messages`. Use the `variables` object to substitute numbered placeholders — the key `"1"` maps to `{{1}}` in the template body, `"2"` to `{{2}}`, and so on.

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

The delivered message reads:

> Olá, João Silva! Sua consulta está marcada para 14h com Dra. Helena.

## Language codes

The `language` field uses IETF BCP 47 codes. You must use the exact language code the template was approved with — mixing languages causes the message to fail.

| Code    | Language                |
| ------- | ----------------------- |
| `pt_BR` | Portuguese (Brazil)     |
| `en_US` | English (United States) |
| `es_AR` | Spanish (Argentina)     |
| `es_MX` | Spanish (Mexico)        |
| `fr_FR` | French (France)         |

<Tip>
  If you serve customers in multiple locales, create separate templates for each language rather than relying on a single template. Meta evaluates each language version independently, so approval in `pt_BR` does not automatically approve `en_US`.
</Tip>