> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência de templates do WhatsApp
> Referência de categorias, formatos de cabeçalho, tipos de botões, sintaxe de variáveis, templates de cupão e localização, e ciclo de vida de submissão.
Esta página é uma referência para os blocos de construção de um template do WhatsApp — categorias, cabeçalhos, corpo, botões, variáveis, tipos avançados de templates e o ciclo de vida de submissão. Para o passo a passo de criação e teste de um template, veja [Templates](/app/templates). Para os limites de formato de mídia, veja [Cabeçalhos de mídia](/app/media-in-template-headers).
## Categorias
Todo template tem exatamente uma categoria, definida quando você o submete à Meta. A categoria determina o **preço** e **qual conteúdo é permitido**.
| Categoria | Use para | Observações |
| ---------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Marketing** | Promoções, ofertas, convites para eventos, reengajamento | Tier mais caro; sujeito a regras de opt-in |
| **Utilidade** | Atualizações de pedidos, alertas de conta, lembretes, acompanhamentos de fluxos iniciados pelo usuário | Mais barato que Marketing; o conteúdo deve estar relacionado a uma transação ou solicitação específica |
| **Autenticação** | Senhas de uso único e códigos de verificação de conta | Formato estrito; conteúdo de marketing não é permitido; tier mais barato |
Se a Meta achar que seu template não corresponde à categoria escolhida, ele será **rejeitado** ou **recategorizado** — comum com conteúdo de Marketing submetido como Utilidade. A categoria também pode mudar automaticamente conforme a Meta observa padrões de uso, o que altera a tarifa cobrada.
## Formatos de cabeçalho
O cabeçalho de um template é opcional. Quando presente, pode ser um dos seguintes:
* **TEXT** — texto curto, pode incluir uma variável.
* **IMAGE** — JPEG ou PNG, até 5 MB. Veja [Cabeçalhos de mídia](/app/media-in-template-headers).
* **VIDEO** — MP4 ou 3GPP com H.264/AAC, até 16 MB.
* **DOCUMENT** — PDF (mais confiável), formatos do Office ou texto simples. Até 100 MB. O nome do arquivo é visível para o destinatário.
* **LOCATION** — latitude, longitude, nome e endereço. Útil para visitas a lojas ou confirmações de entrega.
Cabeçalhos de mídia podem ser anexados como um **handle de mídia** (carregado uma vez na Meta) ou como uma **URL HTTPS pública** buscada a cada envio. Veja [Cabeçalhos de mídia](/app/media-in-template-headers) para entender os trade-offs.
## Corpo e variáveis
O corpo é o texto principal da mensagem. As variáveis usam **chaves duplas com índice baseado em 1**:
```text theme={null}
Hi {{1}}, your order {{2}} has shipped. Track it here: {{3}}
```
Regras:
* Os números devem ser sequenciais começando em `{{1}}` — não é possível pular índices.
* Forneça um valor de exemplo para cada variável ao submeter. A Meta usa os exemplos para avaliar o template.
* Mantenha as variáveis com valores curtos e previsíveis. Blocos longos colados são uma causa comum de rejeição.
A mesma sintaxe `{{n}}` é usada em **cabeçalhos TEXT** e **botões de URL** (veja abaixo).
### Formatação no corpo
O WhatsApp suporta um conjunto limitado de formatação inline nos corpos de templates:
* **Negrito** com `*asteriscos*`
* **Itálico** com `_sublinhados_`
* **Tachado** com `~tildes~`
* **Monoespaçado** com triplo backtick
Use formatação com moderação. Templates com muita formatação são frequentemente rejeitados por parecerem spam.
## Rodapé
Texto simples opcional exibido após o corpo. Sem variáveis, sem formatação.
## Botões
Um template pode incluir até **10 botões no total**, agrupados como respostas rápidas ou call-to-action. As combinações que a Meta permite mudaram ao longo das versões da Cloud API; os padrões mais confiáveis são:
| Tipo de botão | O que faz | Exemplo | Variável? |
| ---------------- | ----------------------------------------------------------------- | ------------------------------- | --------------------------------- |
| **QUICK\_REPLY** | Envia uma resposta de texto predefinida de volta para sua empresa | `Sim, sou eu` | Não |
| **URL** | Abre uma página web | `https://acme.com/orders/{{1}}` | Uma na URL |
| **PHONE** | Liga para um número de telefone | `+44 20 7946 0000` | Não |
| **COPY\_CODE** | Copia um código para a área de transferência | `SAVE20` | Uma para o código |
| **FLOW** | Abre um Flow do WhatsApp | (ID do Flow vinculado) | Variáveis através do próprio Flow |
| **CATALOG** | Abre seu catálogo do WhatsApp | (ID do catálogo vinculado) | Não |
| **MPM** | Lançador de Mensagem Multi-Produto | (produtos do catálogo) | Não |
| **VOICE\_CALL** | Inicia uma chamada de voz pelo WhatsApp (onde suportado) | (seu número de empresa) | Não |
Botões de resposta rápida são úteis quando você quer uma resposta estruturada (bom para análises). Botões de URL e telefone são úteis para direcionar destinatários do WhatsApp para o restante da sua stack. Botões FLOW são a porta de entrada para Flows orientados por formulários do HubSpot, nos quais a Flowella é especializada.
## Tipos especializados de templates
A Meta tem vários tipos especializados de templates de marketing que adicionam funcionalidades extras à estrutura base.
### Templates de carrossel
Um template de carrossel exibe vários cards em rolagem horizontal, cada um com sua própria mídia, corpo e botões. Útil para vitrines de catálogo, ofertas multi-produto ou comparações de recursos.
* **Até 10 cards** por template.
* Cada card tem seu próprio cabeçalho de imagem ou vídeo (um tipo de mídia por template — todos imagens ou todos vídeos, não misturados).
* Cada card pode ter até **2 botões** (Resposta rápida, URL ou Telefone).
* O corpo de cada card pode ter até 3 variáveis.
A aprovação é por template (não por card), portanto, todos os cards devem cumprir a categoria escolhida.
### Templates de oferta por tempo limitado (LTO)
Templates LTO renderizam um timer de contagem regressiva abaixo do corpo. Quando o timer expira, a oferta é mostrada como expirada e tocar no CTA não faz nada.
* Um parâmetro de **código da oferta** é obrigatório e mostrado ao usuário.
* Um **epoch de expiração (em segundos)** é obrigatório.
* O botão CTA geralmente é um Copiar Código ou URL.
Melhor para ofertas genuinamente limitadas no tempo — usar LTO para ofertas que não expiram realmente gera reclamações de usuários e recategorização para fora de Marketing.
### Templates de código de cupom
Como LTO, mas sem a contagem regressiva — apenas um código que o usuário pode copiar com um toque.
* O código pode ter **até 20 caracteres** (recentemente aumentado de 15).
* O botão Copiar Código copia o valor fornecido no **momento do envio** — o campo `example` do template é apenas um placeholder e nunca é enviado.
* Em **Templates → aba Enviar** e na **caixa de diálogo de template da caixa de entrada**, os templates de código de cupom apresentam uma entrada dedicada **Botões de código de cupom** onde você digita os códigos que realmente quer enviar (um por linha de destinatário em envios em massa). Os rótulos antigos "Copiar código" / "Botões de copiar código de cupom" foram substituídos por este único termo consistente.
### Templates de autenticação
Templates especializados para entrega de OTP. Três subtipos:
* **Autopreenchimento com um toque** — usa a API de autopreenchimento do Android para popular o OTP automaticamente quando o usuário toca no botão. Melhor UX onde suportado.
* **Copiar código** — mostra um botão Copiar; o usuário cola o código no seu app. Funciona em qualquer lugar.
* **Zero toques** — para remetentes confiáveis, o OTP pode ser entregue sem nenhum toque (uma chamada de API automática do cliente WhatsApp para seu app). Elegibilidade estrita.
Templates de autenticação têm o preço mais barato por mensagem, mas as regras de conteúdo mais estritas: sem conteúdo de marketing, sem texto adicional além do próprio código.
### Templates de localização
Carregam uma localização exata no cabeçalho, úteis para visitas a lojas, confirmações de entrega ou locais de eventos. O usuário pode abrir a localização em seu app de mapas com um toque.
**Cabeçalho de localização como variáveis**
O cabeçalho LOCATION carrega até quatro campos — **latitude**, **longitude**, **nome** e **endereço** — e a Flowella trata todos os quatro como variáveis normais de template.
* Os valores que você digitou no editor (em `_flowellaEditor.headerLocationPreview`) tornam-se o **padrão** enviado se nenhuma substituição for fornecida.
* As caixas de diálogo de **Testar Template** e de envio da caixa de entrada expõem os quatro campos como entradas regulares de variável.
* A ação [Enviar Template do WhatsApp](/hubspot/workflow-actions#send-whatsapp-template) do HubSpot passa os quatro valores através de `headerLocation` para que um workflow possa personalizar o pin por destinatário.
Se você omitir algum dos quatro no momento do envio, a Flowella usa o valor da prévia do editor para esse campo.
## Ciclo de vida de submissão
Quando você submete um template a partir da Flowella, ele passa por estes estados:
Salvo na Flowella, mas ainda não enviado à Meta.
Submetido à Meta e em análise. A maioria dos templates passa pela análise automatizada da Meta em minutos, mas alguns são encaminhados para revisão humana. O editor da Flowella informa que a aprovação **pode levar até 12 horas** e **envia um e-mail** no momento em que o status muda — você não precisa ficar atualizando.
Ativo e utilizável. Você pode enviá-lo da caixa de entrada, da API e de workflows do HubSpot.
A Meta recusou o template. O motivo da rejeição aparece na página do template. Edite e reenvie.
A Meta revisou o feedback de qualidade e sinalizou o template. Geralmente é o precursor de PAUSED.
A Meta restringiu temporariamente o envio do template, geralmente por feedback dos destinatários ou baixa qualidade. Volta automaticamente se a qualidade se recuperar.
A Meta restringiu permanentemente o template. Deve ser reenviado como um novo template (geralmente recategorizado) se você quiser usar o conteúdo novamente.
## Avaliação de qualidade
Uma vez aprovado, cada template constrói sua própria avaliação de qualidade — separada da [avaliação de qualidade do número de telefone](/meta/quality-score). A avaliação de nível de template usa a mesma escala Verde/Amarelo/Vermelho e é impulsionada principalmente por:
* Taxa de bloqueio entre os destinatários
* Frequência de ações de "Denunciar" no WhatsApp
* Baixo engajamento sustentado (sem respostas, sem cliques em links)
Avaliações Amarelo e Vermelho de template podem fazer a Meta pausar o template mesmo se a avaliação do próprio número estiver Verde. Acompanhe a qualidade do template em **Flowella → Templates** junto com a avaliação a nível de número.
## Time-to-live (TTL)
Templates podem ter um **time-to-live** que controla por quanto tempo a Meta tentará a entrega antes de desistir. Útil para envios sensíveis ao tempo, como convites para promoções relâmpago.
* **Padrão:** 30 dias para a maioria dos templates.
* **Templates OTP / autenticação:** muito mais curto (alguns minutos por padrão), já que códigos não têm valor uma vez expirados.
* **TTL personalizado:** pode ser definido por envio para alguns tipos de template.
Se um template expira antes da entrega (telefone do destinatário offline, conta pausada etc.), ele conta como envio para fins de cobrança, mas nunca chega ao cliente.
## Motivos comuns de rejeição
* **Conteúdo promocional submetido como Utilidade.** Reenvie como Marketing.
* **Exemplos de variáveis que não correspondem ao corpo** — por exemplo, exemplos que contêm links que o corpo não justifica.
* **Texto do corpo ou cabeçalho que parece spam** — capitalização excessiva, "Clique aqui", "Grátis!!!", múltiplos pontos de exclamação.
* **URLs de cabeçalho de mídia quebradas ou inacessíveis.**
* **Texto de rodapé que contradiz o corpo.**
* **Templates genéricos** que poderiam ser enviados por qualquer pessoa — `Olá {{1}}, oferta especial para você` sem detalhes é genérico demais para aprovação em marketing.
* **Variáveis no contexto errado** — usar uma variável em um lugar que a Meta não permite (por exemplo, alguns tipos de botão).
* **Nome de exibição não corresponde à marca** do conteúdo do template. Se o nome de exibição da WABA é "Acme" e o template promove "Beta Co", será rejeitado.
Edite uma cópia de um template APPROVED em vez do original, para manter uma versão funcional enquanto a Meta revisa as mudanças. O **Templates → Duplicar** da Flowella faz isso por você.
## Guias relacionados
* [Templates](/app/templates) — o passo a passo de construção de um template
* [Cabeçalhos de mídia](/app/media-in-template-headers) — referência de formato de mídia
* [Template rejeitado](/troubleshooting/template-rejected) — diagnóstico de rejeições
* [Pontuação de qualidade](/meta/quality-score) — como a qualidade do número de telefone interage com a qualidade do template
* [Limites de mensagens](/meta/messaging-limits) — o sistema de tiers que limita quantos templates você pode enviar