> ## 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. # Referência de regras de templates > Todas as regras do validador de templates do WhatsApp mapeadas para os motivos de rejeição da Meta — com exemplos de FAÇA e NÃO FAÇA para cada uma. Esta página é a referência definitiva para todas as regras estruturais que o Switchbord verifica antes de enviar um template à Meta. Cada seção está associada ao código de erro que o validador do lado do cliente emite (veja BORD-335), para que você possa ir direto do aviso vermelho no editor até a correção. Todas as regras são aplicadas tanto pelo linter do lado do cliente do Switchbord quanto pelo validador de envio da Meta. O revisor humano da Meta adiciona uma segunda camada de verificações de conteúdo além dessas (veja [Templates de marketing](/pt-BR/whatsapp/marketing-templates)). ## name-regex Os nomes de templates são usados como identificadores estáveis em toda a Meta, nos webhooks e no nosso banco de dados. A Meta exige apenas caracteres minúsculos para que os nomes sejam seguros para URLs e fáceis de comparar (diff) entre diferentes BSPs. **Regra:** `^[a-z][a-z0-9_]{0,511}$` — apenas letras minúsculas, dígitos e underscores. Sem espaços, hífens, letras maiúsculas, pontos ou caracteres acentuados. Deve ser único por WABA e por idioma. **FAÇA** ```text theme={null} booking_confirmed invoice_ready winback_30d ``` **NÃO FAÇA** ```text theme={null} Booking Confirmed // espaços e maiúsculas invoice-ready // hífen booking.v2 // ponto prenotazioneConfermata // camelCase ``` Documentação da Meta: [Diretrizes de templates — nomenclatura](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines). ## leading-variable A Meta rejeita textos de corpo que começam com um placeholder porque isso é exibido de forma estranha no celular e não dá ao modelo nenhuma âncora para a classificação de categoria. Um corpo que começa com um nome ou saudação parece uma mensagem; um que começa com `{{1}}` parece um vazamento de template. **FAÇA** ```text theme={null} Ciao {{1}}, la tua prenotazione è confermata. ``` **NÃO FAÇA** ```text theme={null} {{1}} è confermata. ``` Documentação da Meta: [Diretrizes de templates de mensagem](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## trailing-variable O espelho da regra leading-variable. Um corpo que termina em `{{N}}` — mesmo com um ponto final depois — é rejeitado. Adicione pelo menos uma palavra fixa após o último placeholder, idealmente uma frase completa de contexto. **FAÇA** ```text theme={null} Rimborso di {{1}} EUR accreditato entro 7 giorni. ``` **NÃO FAÇA** ```text theme={null} Rimborso di {{1}} ``` Documentação da Meta: [Diretrizes de templates de mensagem](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## adjacent-variables Dois placeholders com apenas espaço em branco ou pontuação entre eles são rejeitados. A Meta não consegue renderizar a fronteira de forma limpa nem classificar a intenção quando o corpo é efetivamente uma lista de parâmetros. Coloque pelo menos uma palavra real entre cada par. **FAÇA** ```text theme={null} Ciao {{1}}, il tuo codice ordine è {{2}}. ``` **NÃO FAÇA** ```text theme={null} {{1}}, {{2}} {{1}} {{2}} {{1}}-{{2}} ``` Documentação da Meta: [Diretrizes de templates de mensagem](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## missing-example Todo `{{n}}` em um `HEADER`, `BODY` ou botão de URL dinâmico deve ter um exemplo realista correspondente. A Meta usa os exemplos para renderizar a pré-visualização mostrada aos revisores e para classificar a categoria do template. Um template com placeholders e sem exemplos é rejeitado no momento do envio. **FAÇA** ```json theme={null} { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ships today.", "example": { "body_text": [["Marco Rossi", "GBV-2025-0042"]] } } ``` **NÃO FAÇA** ```json theme={null} { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ships today." } ``` Documentação da Meta: [Criar e enviar um template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates). ## example-count-mismatch O tamanho do array de exemplos deve ser igual ao número de placeholders distintos. Três tokens `{{n}}` exigem exatamente três strings de exemplo — nem duas, nem quatro. Essa verificação é executada por componente (corpo, texto do cabeçalho, botão de URL). **FAÇA** ```json theme={null} "text": "Hi {{1}}, order {{2}} — total {{3}} EUR.", "example": { "body_text": [["Marco", "GBV-0042", "450,00"]] } ``` **NÃO FAÇA** ```json theme={null} "text": "Hi {{1}}, order {{2}} — total {{3}} EUR.", "example": { "body_text": [["Marco", "GBV-0042"]] } // apenas 2 exemplos para 3 variáveis ``` Documentação da Meta: [Parâmetros de template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#examples). ## numeric-only-example Os valores de exemplo devem ser realistas — ou seja, devem conter caracteres alfabéticos ou um token alfanumérico claramente significativo (valor monetário com símbolo, uma data, um código de pedido). Um número isolado, um único símbolo ou uma string parecida com código sem contexto é rejeitado porque não representa como um destinatário real verá a mensagem. **FAÇA** ```json theme={null} "example": { "body_text": [["20%", "Parigi", "15 maggio 2025", "FLASH20"]] } ``` **NÃO FAÇA** ```json theme={null} "example": { "body_text": [["20", "5", "2025", "20"]] } // números isolados "example": { "body_text": [["%", "€", "—", "."]] } // apenas símbolos ``` Incorpore a unidade ao exemplo — escreva `"20%"`, e não `"20"` com o `%` ao lado no corpo. Isso elimina a heurística de "número isolado" e é renderizado da mesma forma. Documentação da Meta: [Valores de exemplo](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#examples). ## sequential-numbering Os placeholders devem começar em `{{1}}` e seguir sequencialmente, sem lacunas e sem duplicatas. `{{1}}, {{2}}, {{3}}` é válido; `{{1}}, {{3}}` não é; `{{2}}, {{3}}` não é (deve começar em 1). O validador extrai os índices únicos, os ordena e verifica se a lista resultante é igual a `[1..N]`. **FAÇA** ```text theme={null} Hi {{1}}, order {{2}} ships {{3}}. ``` **NÃO FAÇA** ```text theme={null} Hi {{1}}, order {{3}}. // faltando {{2}} Hi {{2}}, welcome. // não começa em 1 Hi {{1}}, {{1}} again. // índice duplicado ``` Documentação da Meta: [Parâmetros de template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates). ## params-words-ratio Um template no qual os placeholders dominam o texto fixo se assemelha a um despejo de dados brutos e é sinalizado durante a revisão de conteúdo. O linter do Switchbord alerta quando a proporção de variáveis em relação ao total de palavras excede aproximadamente **1 em 4** — um template com três tokens `{{n}}` deve ter pelo menos doze palavras de texto fixo ao redor deles. **FAÇA** ```text theme={null} Ciao {{1}}, la tua prenotazione per {{2}} è confermata. Il codice viaggio è {{3}}, conservalo per il check-in. ``` (12 palavras fixas em torno de 3 placeholders) **NÃO FAÇA** ```text theme={null} {{1}}: {{2}} — {{3}} ``` (3 placeholders, 2 tokens fixos) Documentação da Meta: [Qualidade do template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/guidelines). ## length-caps Cada componente tem um limite rígido de caracteres. Conte a string bruta do template, incluindo os placeholders — a expansão em tempo de execução não conta para o limite. | Componente | Limite | | --------------- | ------------------- | | Texto do HEADER | **60** caracteres | | Texto do BODY | **1024** caracteres | | Texto do FOOTER | **60** caracteres | | Rótulo do botão | **25** caracteres | **FAÇA** ```text theme={null} HEADER: "Estate 2025 — offerte" (22 caracteres) FOOTER: "Rispondi STOP per non ricevere più." (35 caracteres) Button: "Scarica PDF" (11 caracteres) ``` **NÃO FAÇA** ```text theme={null} HEADER: "Offerta esclusiva di fine stagione ..." (> 60 caracteres) Button: "Scopri tutte le offerte di questo mese" (> 25 caracteres) ``` Documentação da Meta: [Componentes do template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). ## button-limits Os botões têm limites rígidos por tipo. Exceder qualquer um desses limites rejeita o template inteiro no momento do envio. | Tipo de botão | Máximo | | -------------- | ------------------------------ | | `QUICK_REPLY` | **3** por template | | `URL` | **2** (máx. 1 sufixo dinâmico) | | `PHONE_NUMBER` | **1** | | `COPY_CODE` | **1** | | `FLOW` | **1** | | **Total** | **10** somando todos os tipos | Botões de URL dinâmicos devem ter `{{1}}` como única variável, aparecendo **no final** do caminho da URL ou do valor de consulta — nunca no hostname. **FAÇA** ```json theme={null} "buttons": [ { "type": "QUICK_REPLY", "text": "Mare" }, { "type": "QUICK_REPLY", "text": "Montagna" }, { "type": "QUICK_REPLY", "text": "Città d'arte" }, { "type": "URL", "text": "Scarica PDF", "url": "https://gbviaggi.it/fattura/{{1}}", "example": ["https://gbviaggi.it/fattura/2025-0142"] } ] ``` **NÃO FAÇA** ```json theme={null} "buttons": [ { "type": "QUICK_REPLY", "text": "A" }, { "type": "QUICK_REPLY", "text": "B" }, { "type": "QUICK_REPLY", "text": "C" }, { "type": "QUICK_REPLY", "text": "D" } // 4 > máximo de 3 ] "url": "https://{{1}}.example.com" // variável no hostname "url": "https://example.com/{{1}}/{{2}}" // mais de uma variável ``` Documentação da Meta: [Botões de template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#buttons). ## component-ordering Os componentes de um template devem aparecer na ordem `HEADER → BODY → FOOTER → BUTTONS`. Cada componente pode aparecer no máximo uma vez, exceto `BODY`, que é obrigatório exatamente uma vez. A Meta normaliza a ordem em alguns casos, mas rejeita duplicatas e tipos desconhecidos com o código 100. **FAÇA** ```json theme={null} "components": [ { "type": "HEADER", "format": "TEXT", "text": "Estate 2025" }, { "type": "BODY", "text": "Ciao {{1}}, ..." }, { "type": "FOOTER", "text": "Rispondi STOP." }, { "type": "BUTTONS", "buttons": [ ... ] } ] ``` **NÃO FAÇA** ```json theme={null} "components": [ { "type": "BODY", "text": "..." }, { "type": "HEADER", "format": "TEXT", "text": "..." }, // posição errada { "type": "BODY", "text": "..." } // duplicado ] ``` Documentação da Meta: [Componentes do template](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). ## footer-has-variables Os rodapés servem para texto estático e legalmente relevante — a identidade do remetente, a instrução de opt-out, um aviso legal. Eles não podem conter placeholders `{{n}}`. Coloque os dados dinâmicos no corpo. **FAÇA** ```json theme={null} { "type": "FOOTER", "text": "GB Viaggi — Rispondi STOP per non ricevere più offerte." } ``` **NÃO FAÇA** ```json theme={null} { "type": "FOOTER", "text": "Sent to {{1}} on {{2}}" } ``` Documentação da Meta: [Componentes do template — rodapé](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). *** ## Conjunto de regex de referência rápida Se você estiver escrevendo seu próprio validador ou criando scripts para verificações em massa, os regex canônicos são: ```js theme={null} const PLACEHOLDER = /\{\{(\d+)\}\}/g; const adjacentVars = /\{\{\d+\}\}[^A-Za-zÀ-ÿ0-9]{0,3}\{\{\d+\}\}/; const startsWithVar = /^\s*\{\{\d+\}\}/; const endsWithVar = /\{\{\d+\}\}\s*[.!?]*\s*$/; const bareNumberExample = /^[\d\s.,%$€£¥+\-]+$/; const nameRule = /^[a-z][a-z0-9_]{0,511}$/; const langRule = /^[a-z]{2}(_[A-Z]{2})?$/; const dynamicUrl = /^https?:\/\/[^{}\s]+?(\{\{1\}\})?$/; ``` ## Veja também * [Seu primeiro template](/getting-started/first-template) — passo a passo completo. * [Templates de marketing](/pt-BR/whatsapp/marketing-templates) — regras específicas por categoria e opt-out. * [Endpoints da API de templates](/api-reference/template-endpoints) — envio programático.