> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Seu primeiro template de WhatsApp
> Crie, valide e envie para aprovação seu primeiro template de mensagem do WhatsApp no Switchbord — do editor em branco à aprovação pela Meta.
Este passo a passo leva você de um editor de template em branco a um template de WhatsApp aprovado em cerca de quinze minutos. Você só precisa de uma WhatsApp Business Account (WABA) conectada e de um operador com acesso às configurações.
## O que é um template de WhatsApp
Um template de WhatsApp é uma definição de mensagem reutilizável que a Meta pré-aprova antes que você possa enviá-la. Toda **mensagem de saída iniciada pela empresa** — uma confirmação de reserva, uma notificação de fatura, uma promoção sazonal — precisa referenciar um template aprovado. O template carrega a estrutura (texto, botões, mídia de cabeçalho) e seu código em runtime preenche os placeholders `{{1}}`, `{{2}}` para cada destinatário.
Templates são a única forma de reengajar um contato fora da janela de atendimento ao cliente de 24 horas, portanto uma biblioteca limpa e aprovada é a base de toda campanha e jornada que você vai executar no Switchbord.
## Por que templates precisam de aprovação da Meta
O WhatsApp é um canal que prioriza o consentimento. Para proteger os usuários de spam, a Meta exige que todo template de empresa passe por um pipeline de pré-aprovação que verifica:
* **Estrutura** — os placeholders estão bem formados, os exemplos são realistas, o corpo não começa nem termina com uma variável, os botões estão dentro dos limites.
* **Adequação de categoria** — o conteúdo realmente corresponde a `UTILITY`, `MARKETING` ou `AUTHENTICATION`.
* **Política** — sem setores proibidos, sem alegações enganosas, opt-out presente em mensagens de marketing.
Você não pode publicar um template que não passou por essa revisão. O editor do Switchbord executa localmente as mesmas verificações estruturais antes de enviar, de modo que a maioria das violações é detectada antes mesmo de a Meta ver o payload. Veja a [referência de regras de templates](/pt-BR/whatsapp/template-rules) para a lista completa.
## Passo a passo
### 1. Abra o editor de templates
Na barra lateral esquerda, clique em **Templates**. Você verá a biblioteca de templates que este workspace já enviou, filtrável por status (`draft`, `pending_approval`, `approved`, `rejected`).
Clique em **New template** no canto superior direito. Um editor em branco é aberto, com quatro painéis: metadados, componentes, preview e validação.
### 2. Escolha uma categoria
A categoria define a cobrança, a tolerância de aprovação e quais componentes você pode usar.
| Categoria | Use quando | Faixa de cobrança |
| ---------------- | ---------------------------------------------------- | ----------------- |
| `UTILITY` | Atualizações de pedido, reserva, fatura, compromisso | Mais baixa |
| `MARKETING` | Promoções, campanhas, reengajamento | Mais alta |
| `AUTHENTICATION` | Códigos de uso único, MFA | Fixa por região |
Escolha a que corresponde à **intenção** da mensagem, não ao conteúdo. Escrever "20% de desconto" em um template `UTILITY` será rejeitado ou reclassificado silenciosamente pela Meta. Veja [Templates de marketing](/pt-BR/whatsapp/marketing-templates) para a árvore de decisão completa.
Deixe **Allow category change** habilitado em rascunhos de marketing. Isso permite que a Meta corrija automaticamente a categoria durante a revisão, em vez de rejeitar de imediato.
### 3. Escreva o corpo com variáveis
Componha o texto do corpo e use `{{1}}`, `{{2}}`, `{{3}}` para substituições em tempo de execução.
```text Example body theme={null}
Ciao {{1}}, la tua prenotazione per {{2}} è confermata. Il codice è {{3}}.
```
Três regras para internalizar desde o primeiro dia:
1. **Nunca comece ou termine o corpo com um placeholder.** Prefixe com uma saudação, finalize com um ponto final mais contexto.
2. **Nunca coloque dois placeholders adjacentes** com apenas espaço em branco ou pontuação entre eles (`{{1}}, {{2}}`). Coloque pelo menos uma palavra entre eles.
3. **Numere sequencialmente** começando em `{{1}}`. Sem lacunas, sem repetições.
O painel de validação em tempo real destaca as violações inline e traz links para a regra exata.
### 4. Adicione exemplos para cada variável
Cada `{{n}}` precisa de um valor de exemplo realista. A Meta usa esses exemplos para avaliar se o template corresponde à categoria e para renderizar um preview durante a revisão.
```json Example body_text payload theme={null}
"example": {
"body_text": [["Marco Rossi", "Roma — Hotel Colosseo", "GBV-2025-0042"]]
}
```
Evite:
* Números isolados (`"20"`, `"5"`)
* Símbolos isolados (`"%"`, `"€"`)
* O texto literal do placeholder (`"{{1}}"`)
* URLs se o corpo não contiver nenhuma
Incorpore a unidade no próprio exemplo — escreva `"20%"` para o fragmento de corpo `"sconto del {{1}}"`, não apenas `"20"`.
### 5. Envie para aprovação
Clique em **Submit for approval**. O Switchbord executa a validação final do lado do cliente e depois faz um `POST` para o endpoint `/message_templates` da Meta. Em caso de sucesso, o status local muda para `pending_approval` e o template desaparece do filtro de rascunhos.
## O que acontece depois
A revisão da Meta é quase sempre rápida:
* **Minutos** para templates `UTILITY` bem formados que correspondem à categoria.
* **Uma ou duas horas** para templates `MARKETING` que passam por revisão de conteúdo.
* **Até 24 horas** sob carga elevada ou quando um revisor humano é envolvido.
Você não precisa fazer polling. Nosso manipulador de webhook escuta o evento `message_template_status_update` e muda a linha para `approved`, `rejected`, ou registra uma migração de categoria. A lista de Templates é atualizada em tempo real via Supabase Realtime.
## Se o template for rejeitado
Uma rejeição não é um fracasso — é apenas um item de checklist. O Switchbord armazena o motivo legível da Meta na coluna `rejection_reason` e o exibe no topo do editor.
Abra o template rejeitado. O banner vermelho mostra o `error_user_msg` da Meta na íntegra — por exemplo, *"Variable parameters cannot be next to each other."*
Toda mensagem corresponde a uma regra na página de [Regras de templates](/pt-BR/whatsapp/template-rules). O código do erro do validador está na âncora da URL.
Duplique o template rejeitado (o original fica bloqueado), aplique a correção e clique em **Submit for approval** novamente. Não há penalidade por reenviar — a Meta limita a 100 templates/hora por WABA, o que é bastante margem.
Se o mesmo template for rejeitado duas vezes por motivos diferentes, isso geralmente significa que a primeira correção mascarou uma segunda violação. Execute **Validate** (linter dry-run, sem chamada à Meta) para detectar ambas antes de reenviar.
## Próximos passos
* [Referência de regras de templates](/pt-BR/whatsapp/template-rules) — todas as regras do validador, com exemplos de FAÇA e NÃO FAÇA.
* [Templates de marketing](/pt-BR/whatsapp/marketing-templates) — aprofundamento na categoria MARKETING, opt-out e migração de categoria.
* [Endpoints da API de templates](/pt-BR/api-reference/template-endpoints) — automatize o gerenciamento de templates a partir dos seus próprios scripts.