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

# Templates

> Crie, sincronize com a Meta e envie templates de mensagem WhatsApp — cabeçalho, corpo, rodapé, botões e variáveis.

# Templates

Templates são modelos de mensagem reutilizáveis. Eles servem para dois propósitos:

1. **Operação manual** — operadores inserem rapidamente respostas padronizadas no Chat.
2. **Envio fora da janela de 24h** — em instâncias **Meta Oficial**, é a única forma de iniciar conversa com um contato que não falou com você nas últimas 24h. Para isso o template precisa estar **aprovado pela Meta**.

***

## Estrutura de um template

Um template é composto por até 4 blocos:

| Bloco         | Obrigatório | Limite                | Aceita variáveis?                        |
| ------------- | ----------- | --------------------- | ---------------------------------------- |
| **Cabeçalho** | Não         | 60 caracteres (texto) | Sim — 1 variável (texto) ou mídia        |
| **Corpo**     | **Sim**     | 1024 caracteres       | Sim — múltiplas variáveis                |
| **Rodapé**    | Não         | 60 caracteres         | **Não**                                  |
| **Botões**    | Não         | até 3 botões          | Sim — apenas em URL com `{{1}}` no final |

### Cabeçalho

Pode ser **texto** ou **mídia** (apenas um por template):

* **TEXT** — até 60 caracteres, com no máximo **1 variável** posicional ou nomeada
* **IMAGE** — JPG, PNG (até 5 MB)
* **VIDEO** — MP4, 3GPP (até 16 MB)
* **DOCUMENT** — PDF (até 100 MB)

Para cabeçalhos de mídia, no momento do envio você passa a URL pública do arquivo.

### Corpo

O texto principal. Pode ter quantas variáveis quiser, desde que respeite o formato escolhido (POSITIONAL ou NAMED — veja abaixo).

### Rodapé

Texto curto, **sempre estático** — sem variáveis. Útil para assinatura, disclaimers ou aviso de opt-out.

### Botões

Até 3 botões por template, dos seguintes tipos:

| Tipo              | O que faz                                                 | Variável?                                                        |
| ----------------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| **QUICK\_REPLY**  | Resposta rápida pré-definida que o contato envia ao tocar | Não                                                              |
| **URL**           | Abre um link no navegador                                 | **Sim** — apenas se o link terminar em `{{1}}` (sufixo dinâmico) |
| **PHONE\_NUMBER** | Disca um número                                           | Não                                                              |

***

## Status do template

| Status        | Significado                                                       |
| ------------- | ----------------------------------------------------------------- |
| **Rascunho**  | Salvo localmente, ainda não enviado para aprovação                |
| **Pendente**  | Aguardando análise da Meta (de minutos até 24h)                   |
| **Aprovado**  | Pronto para uso — pode ser enviado fora da janela 24h             |
| **Pausado**   | Suspenso pela Meta após queda de qualidade — corrija e ressubmeta |
| **Rejeitado** | Recusado — ajuste o conteúdo e reenvie                            |

<Info>
  Em instâncias **Meta Oficial**, só templates **Aprovados** podem ser enviados via API ou agendamento.
  Em instâncias **WhatsApp Business (API)**, o template é enviado como texto livre — não há aprovação.
</Info>

***

## Categorias

| Categoria        | Quando usar                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| **Utilidade**    | Notificações transacionais: confirmações, atualizações de pedido, lembretes |
| **Marketing**    | Promoções, ofertas, comunicação de produtos                                 |
| **Autenticação** | Códigos de verificação, OTP, senhas temporárias                             |

A categoria afeta o custo por conversa cobrado pela Meta e as políticas de aprovação.

***

## Variáveis: POSITIONAL vs NAMED

A Meta aceita **dois formatos de variáveis** — você escolhe um e **não pode misturar**:

### POSITIONAL (`{{1}}`, `{{2}}`, `{{3}}`)

Variáveis numeradas pela ordem de aparição. Útil para templates simples.

```
Olá, {{1}}! Seu pedido {{2}} foi confirmado.
```

No envio, mande `variables: { "1": "João", "2": "12345" }`.

### NAMED (`{{nome}}`, `{{pedido}}`)

Variáveis com nomes descritivos — mais legível e mais robusto a alterações.

```
Olá, {{nome}}! Seu pedido {{pedido}} foi confirmado.
```

No envio, mande `variables: { "nome": "João", "pedido": "12345" }`.

<Warning>
  A Meta **rejeita** templates que misturam `{{1}}` com `{{nome}}`. O builder do Brainchat detecta o formato automaticamente e mostra um aviso se houver mistura.
</Warning>

### Variáveis nativas (auto-preenchidas)

Algumas variáveis são preenchidas automaticamente a partir do contato — você **não precisa** enviá-las (mas pode sobrescrever):

* `nome` — `contacts.name`
* `telefone` — `contacts.phone`
* Outros campos do contato disponíveis no escopo da instância

***

## Criar um template

<Steps>
  <Step title="Novo template">
    Em **Templates**, clique em **Novo Template**.
  </Step>

  <Step title="Informações básicas">
    * **Nome** — identificador interno (ex: `confirmacao_agendamento`)
    * **Categoria** — Utilidade, Marketing ou Autenticação
    * **Idioma** — `pt_BR`, `en_US`, etc.
  </Step>

  <Step title="Montar conteúdo">
    Adicione cabeçalho (texto ou mídia), escreva o corpo, opcionalmente rodapé e botões. O preview mostra como ficará no celular do contato.
  </Step>

  <Step title="Salvar ou enviar para aprovação">
    * **Salvar como rascunho** — fica disponível só na sua conta
    * **Enviar para Meta** — instâncias Meta Oficial: dispara aprovação
  </Step>
</Steps>

***

## Sincronizar com Meta

Em instâncias **Meta Oficial**, o botão **Sincronizar com Meta** na lista de templates:

* Importa templates já aprovados em outras ferramentas
* Atualiza status de templates submetidos (Pendente → Aprovado/Rejeitado)
* Re-vincula `meta_template_id` se a Meta tiver migrado IDs

<Tip>
  Sincronize após cada submissão para acompanhar a aprovação sem precisar abrir o Business Manager.
</Tip>

***

## Enviar via API

Use o endpoint dedicado, que detecta automaticamente o provedor da instância (Meta Oficial ou API Business):

[**POST /send-template-message →**](/api/enviar-template)

Cabeçalho estático, rodapé e botões fixos vão automaticamente — você só passa as **variáveis dinâmicas** no campo `variables`.