> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar Template

> Endpoint POST para envio de mensagens baseadas em templates aprovados (WhatsApp Business) ou texto livre, com substituição automática de variáveis.

# Enviar Template

Envie uma mensagem a partir de um **template cadastrado** na instância. O endpoint detecta automaticamente o provider da instância (WhatsApp Business oficial ou via API) — você **não precisa** informar de qual tipo é o template.

```
POST https://wapi.stegia.com.br/functions/v1/send-template-message
```

<Note>
  Para templates **Meta**, é a única forma de enviar mensagens fora da janela de 24h. O template precisa estar com `meta_status = APPROVED` e sincronizado (`meta_template_id` preenchido).
</Note>

## Headers

| Header           | Valor                                                           |
| ---------------- | --------------------------------------------------------------- |
| `Content-Type`   | `application/json`                                              |
| `X-Client-Token` | Seu token da instância (veja [Autenticação](/api/autenticacao)) |

## Parâmetros do Body

| Campo        | Tipo          | Obrigatório | Descrição                                                                          |
| ------------ | ------------- | ----------- | ---------------------------------------------------------------------------------- |
| `templateId` | string (uuid) | ✅           | ID do template em `message_templates`                                              |
| `instanceId` | string        | ⚠️          | ID da instância. Opcional se o template já estiver vinculado a uma única instância |
| `phone`      | string        | ✅           | Destinatário (`5511999999999`, sem `+` ou formatação)                              |
| `variables`  | object        | ❌           | Mapa de variáveis para preencher BODY, HEADER e BUTTONS                            |

### O que vai automático (não precisa enviar)

Tudo que faz parte do template **aprovado** pela Meta vai automaticamente em todo envio — você **não** precisa repetir na requisição:

* **Cabeçalho de TEXTO sem variável** (ex.: `"Boas-vindas!"`)
* **Rodapé** (sempre estático)
* **Botões fixos**: `QUICK_REPLY`, `PHONE_NUMBER`, `URL` sem variável

Se o template é totalmente estático, basta enviar `templateId`, `instanceId` e `phone` — o `variables` pode ser `{}` ou omitido.

### O que precisa em `variables`

Só os elementos **dinâmicos** do template aprovado:

| Chave                                                   | Quando usar                                                                                                                            |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `nome`, `telefone`                                      | Auto-preenchidas a partir do contato (sobrescritíveis)                                                                                 |
| `header`                                                | Cabeçalho de TEXTO com `{{1}}` **ou** cabeçalho de mídia (IMAGE/VIDEO/DOCUMENT) — informe a URL pública (ou `{ id, link }`) do arquivo |
| `button_1`, `button_2`, `button_3`                      | Sufixo dinâmico de botões `URL` que contêm `{{1}}` no final (numerado pela posição do botão, 1-based)                                  |
| `button_1_payload`                                      | Payload de botão `QUICK_REPLY` (raramente usado)                                                                                       |
| Nomes do corpo (`pedido`, `valor`, ...) ou `"1"`, `"2"` | Substituem as variáveis do BODY conforme o `parameter_format`                                                                          |

A função **detecta automaticamente** o `parameter_format` do template:

* `POSITIONAL` → use chaves numéricas: `{ "1": "João", "2": "12345" }`
* `NAMED` → use os próprios nomes: `{ "nome": "João", "pedido": "12345" }`

<Note>
  A Meta **não permite misturar** `{{1}}` e `{{nome}}` no mesmo template.
</Note>

## Exemplos

### Template Meta NAMED com header de imagem

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/send-template-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "templateId": "00000000-0000-0000-0000-000000000000",
    "instanceId": "INSTANCE_ID",
    "phone": "5511999999999",
    "variables": {
      "nome": "João",
      "pedido": "12345",
      "header": "https://cdn.exemplo.com/banner.jpg",
      "button_1": "https://app.exemplo.com/track/12345"
    }
  }'
```

### Template Meta POSITIONAL simples

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/send-template-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "templateId": "00000000-0000-0000-0000-000000000000",
    "phone": "5511999999999",
    "variables": { "1": "João", "2": "12345" }
  }'
```

### Template totalmente estático (sem variáveis)

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/send-template-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "templateId": "00000000-0000-0000-0000-000000000000",
    "instanceId": "INSTANCE_ID",
    "phone": "5511999999999"
  }'
```

### Template WhatsApp Business (texto livre)

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/send-template-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "templateId": "00000000-0000-0000-0000-000000000000",
    "phone": "5511999999999",
    "variables": { "nome": "João", "pedido": "12345" }
  }'
```

## Respostas

### Sucesso (200)

```json theme={null}
{
  "success": true,
  "provider": "meta",
  "templateId": "uuid",
  "templateName": "boas_vindas",
  "phone": "5511999999999",
  "messageId": "wamid.HBgN..."
}
```

### Erros

| Status | `error`                                     | Quando ocorre                                               |
| ------ | ------------------------------------------- | ----------------------------------------------------------- |
| 400    | `templateId and phone are required`         | Body inválido                                               |
| 400    | `template_not_synced_with_meta`             | Template Meta sem `meta_template_id`                        |
| 400    | `template_not_approved`                     | Status do template Meta ≠ APPROVED                          |
| 400    | `missing_variables`                         | Faltou variável (campo `missing[]` lista quais)             |
| 400    | `meta_outbound_channel_not_configured`      | Instância Meta sem `instance_id`                            |
| 403    | `Template does not belong to this instance` | `instanceId` divergente do template                         |
| 404    | `Template not found` / `Instance not found` | IDs inválidos                                               |
| 502    | `meta_template_send_failed`                 | Falha vinda do provedor WhatsApp Business (campo `details`) |