> ## 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 do modelo WhatsApp: categorias, cabeçalhos, botões

> Referência para categorias de modelos WhatsApp, formatos de cabeçalho, tipos de botão, sintaxe de variáveis, modelos de cupão e localização e o ciclo de vida da submissão.

Esta página é uma referência para os blocos de construção de um modelo WhatsApp — categorias, cabeçalhos, corpo, botões, variáveis, tipos de modelo avançados e o ciclo de vida de submissão. Para o passo a passo de criar e testar um modelo, consulte [Modelos](/pt/app/templates). Para limites de formato de media, consulte [Cabeçalhos de media](/pt/app/media-in-template-headers).

## Categorias

Cada modelo tem exatamente uma categoria, definida quando o submete à Meta. A categoria determina o **preço** e o **conteúdo permitido**.

| Categoria | Use para | Notas |
| - | - | - |
| **Marketing** | Promoções, ofertas, convites para eventos, re-engajamento | Nível mais caro; sujeito a regras de opt-in |
| **Utility** | Atualizações de encomenda, alertas de conta, lembretes, seguimentos de um fluxo iniciado pelo utilizador | Mais barato que Marketing; o conteúdo deve estar relacionado com uma transação ou pedido específico |
| **Authentication** | Palavras-passe únicas e códigos de verificação de conta | Formato estrito; nenhum conteúdo de marketing permitido; nível mais barato |

Se a Meta achar que o seu modelo não corresponde à categoria escolhida, será **rejeitado** ou **recategorizado** — comum com conteúdo de Marketing submetido como Utility. A categoria também pode mudar automaticamente à medida que a Meta observa padrões de uso, o que depois altera a taxa que lhe é cobrada.

## Formatos de cabeçalho

O cabeçalho de um modelo é opcional. Quando presente, pode ser um de:

* **TEXT** — string curta, pode incluir uma variável.
* **IMAGE** — JPEG ou PNG, máx. 5 MB. Consulte [Cabeçalhos de media](/pt/app/media-in-template-headers).
* **VIDEO** — MP4 ou 3GPP com H.264/AAC, máx. 16 MB.
* **DOCUMENT** — PDF (mais fiável), formatos Office ou texto simples. Máx. 100 MB. O editor tem um campo **Nome de ficheiro do documento** que assume o nome do ficheiro carregado; o valor que aí define é o que o destinatário vê na bolha de documento do WhatsApp, portanto escolha algo descritivo como `Acme-Encomenda-12345-Recibo.pdf`.
* **LOCATION** — latitude, longitude, nome e endereço. Útil para visitas a lojas ou confirmações de entrega.

Cabeçalhos de media podem ser anexados como um **handle de media** (carregado uma vez para a Meta) ou como um **URL HTTPS público** obtido por envio. Consulte [Cabeçalhos de media](/pt/app/media-in-template-headers) para as compensações.

## Corpo e variáveis

O corpo é o texto principal da mensagem. As variáveis usam **chavetas duplas com um índice baseado em 1**:

```text theme={null}
Olá {{1}}, a sua encomenda {{2}} foi enviada. Acompanhe aqui: {{3}}
```

Regras:

* Os números devem ser sequenciais a partir de `{{1}}` — não pode saltar índices.
* Forneça um valor de exemplo para cada variável quando submete. A Meta usa os exemplos para avaliar o modelo.
* Mantenha as variáveis em valores curtos e previsíveis. Blocos longos colados são um motivo comum de rejeição.

A mesma sintaxe `{{n}}` é usada em **cabeçalhos TEXT** e **botões URL** (ver abaixo).

### Formatação no corpo

O WhatsApp suporta um conjunto limitado de formatação inline em corpos de modelo:

* **Negrito** com `*asteriscos*`
* **Itálico** com `_sublinhados_`
* **Rasurado** com `~tis~`
* **Monoespaçado** com três backticks

Use a formatação com moderação. Modelos com formatação pesada são frequentemente rejeitados por parecerem spam.

## Rodapé

Texto simples opcional mostrado após o corpo. Sem variáveis, sem formatação.

## Botões

Um modelo pode incluir até **10 botões no total**, agrupados como quick replies ou call-to-action. As combinações que a Meta permite mudaram ao longo das versões da Cloud API; os padrões mais fiáveis:

| Tipo de botão | O que faz | Exemplo | Variável? |
| - | - | - | - |
| **QUICK\_REPLY** | Envia uma resposta de texto predefinida de volta ao seu negócio | `Sim, sou eu` | Não |
| **URL** | Abre uma página web | `https://acme.com/orders/{{1}}` | Uma no URL |
| **PHONE** | Chama um número de telefone | `+351 21 000 0000` | Não |
| **COPY\_CODE** | Copia um código para a área de transferência | `SAVE20` | Uma para o código |
| **FLOW** | Abre um WhatsApp Flow | (ID do Flow associado) | Variáveis através do próprio Flow |
| **CATALOG** | Abre o seu catálogo WhatsApp | (ID do catálogo associado) | Não |
| **MPM** | Lançador Multi-Product Message | (produtos do catálogo) | Não |
| **VOICE\_CALL** | Inicia uma chamada de voz WhatsApp (onde suportado) | (o seu número de negócio) | Não |

Botões quick reply são úteis quando quer uma resposta estruturada (bom para análises). Botões URL e telefone são úteis para encaminhar destinatários para fora do WhatsApp para a sua stack. Botões FLOW são a porta de entrada para Flows baseados em formulários HubSpot em que o Flowella se especializa.

## Tipos de modelo especializados

A Meta tem vários tipos de modelo de marketing especializados que agregam funcionalidade extra sobre a estrutura base.

### Modelos carrossel

Um modelo carrossel (a Meta chama-lhe carrossel de cartões de media) envia uma bolha de mensagem seguida de até 10 cartões numa rolagem horizontal. Cada cartão tem a sua própria media, texto de corpo opcional e botões. Use carrosséis para mostruários de catálogo, ofertas multi-produto ou comparações de funcionalidades.

* **Apenas Marketing.** Os modelos carrossel só podem usar a categoria **Marketing**.
* **2 a 10 cartões** por modelo.
* **Sem cabeçalho nem rodapé na mensagem.** A mensagem tem apenas um corpo. Em vez disso, cada cartão tem o seu próprio cabeçalho de media, e a mensagem em si não pode ter botões.
* **Um tipo de media por modelo.** Todos os cartões usam um cabeçalho de imagem, ou todos os cartões usam um cabeçalho de vídeo. Não pode misturá-los.
* **O corpo do cartão é opcional, até 160 caracteres.** Se um cartão tiver texto de corpo, todos os cartões precisam de texto de corpo.
* **Até 2 botões por cartão** (Quick reply, URL ou Número de telefone).
* **A mesma estrutura de botões em todos os cartões.** Todos os cartões têm o mesmo número de botões, com os mesmos tipos pela mesma ordem. As etiquetas dos botões, URLs e números de telefone podem variar por cartão.

A aprovação é por modelo (não por cartão), portanto todos os cartões devem cumprir com a categoria Marketing. Consulte a documentação da Meta sobre [modelos de carrossel de cartões de media](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/media-card-carousel-templates) para a especificação completa. Para criar um no Flowella, consulte [Construir um modelo carrossel](/pt/app/templates#build-a-carousel-template).

### Modelos de oferta por tempo limitado (LTO)

Modelos LTO renderizam um cronómetro de contagem decrescente por baixo do corpo. Quando o cronómetro expira, a oferta aparece como expirada e tocar no CTA não faz nada.

* É necessário um parâmetro de **código de negócio** que é mostrado ao utilizador.
* É necessária uma **época de expiração (em segundos)**.
* O botão CTA é normalmente Copy Code ou URL.

Melhor para ofertas genuinamente por tempo limitado — usar LTO para ofertas que na verdade não expiram causa reclamações de utilizadores e recategorização para fora de Marketing.

### Modelos de código de cupão

Como LTO mas sem a contagem decrescente — apenas um código que o utilizador pode copiar com um toque.

* O código pode ter **até 20 caracteres** (recentemente aumentado de 15).
* O botão Copy Code copia o valor fornecido no **momento do envio** — o campo `example` do modelo é apenas um espaço reservado e nunca é enviado.
* Em **Modelos → separador Enviar** e na **janela de modelo da caixa de entrada**, modelos de código de cupão apresentam uma entrada dedicada **Botões de código de cupão** onde escreve os códigos que efetivamente quer enviar (um por linha de destinatário para envios em massa). As etiquetas mais antigas "Copiar código" / "Copiar botões de código de cupão" foram substituídas por este termo único e consistente.

### Modelos de autenticação

Modelos especializados para entrega de OTP. Três subtipos:

* **One-tap autofill** — usa a API de autofill do Android para preencher automaticamente o OTP quando o utilizador toca no botão. Melhor UX onde suportado.
* **Copy code** — mostra um botão Copiar; o utilizador cola o código na sua aplicação. Funciona em todo o lado.
* **Zero-tap** — para remetentes de confiança, o OTP pode ser entregue sem qualquer toque (uma chamada de retorno API automática do cliente WhatsApp para a sua aplicação). Elegibilidade estrita.

Os modelos de autenticação têm o preço por mensagem mais barato mas as regras de conteúdo mais estritas: sem conteúdo de marketing, sem texto de corpo extra além do próprio código.

### Modelos de localização

Levam uma localização de ponto no cabeçalho, útil para visitas a lojas, confirmações de entrega ou locais de eventos. O utilizador pode abrir a localização na sua aplicação de mapas com um toque.

**Cabeçalho de localização como variáveis**

O cabeçalho LOCATION leva até quatro campos — **latitude**, **longitude**, **nome** e **endereço** — e o Flowella trata os quatro como variáveis de modelo normais.

* Os valores que digitou no editor (em `_flowellaEditor.headerLocationPreview`) tornam-se o **valor predefinido** enviado se nenhum override for fornecido.
* As janelas **Testar Modelo** e envio da caixa de entrada expõem os quatro campos como entradas de variável normais.
* A ação [Enviar Modelo WhatsApp](/pt/hubspot/workflow-actions#send-whatsapp-template) do HubSpot passa os quatro valores através de `headerLocation` para que um fluxo de trabalho possa personalizar o pino por destinatário.

Se omitir qualquer um dos quatro no momento do envio, o Flowella recorre ao valor de pré-visualização do editor para esse campo.

## Ciclo de vida da submissão

Quando submete um modelo do Flowella, ele passa por estes estados:

<Steps>
  <Step title="DRAFT">
    Guardado no Flowella mas ainda não enviado à Meta.
  </Step>

  <Step title="PENDING">
    Submetido à Meta e em revisão. A maioria dos modelos passa a revisão automática da Meta em minutos, mas alguns são encaminhados para revisão humana. O editor do Flowella diz-lhe que a aprovação **pode levar até 12 horas** e **envia-lhe email** no momento em que o estado muda — não precisa de atualizar constantemente.
  </Step>

  <Step title="APPROVED">
    Ativo e utilizável. Pode enviá-lo a partir da caixa de entrada, da API e dos fluxos de trabalho HubSpot.
  </Step>

  <Step title="REJECTED">
    A Meta rejeitou o modelo. O motivo da rejeição aparece na página do modelo. Edite e volte a submeter.
  </Step>

  <Step title="FLAGGED">
    A Meta reviu o feedback de qualidade e sinalizou o modelo. Normalmente um precursor de PAUSED.
  </Step>

  <Step title="PAUSED">
    A Meta restringiu temporariamente o envio do modelo, normalmente devido a feedback do destinatário ou baixa qualidade. Volta automaticamente se a qualidade recuperar.
  </Step>

  <Step title="DISABLED">
    A Meta restringiu permanentemente o modelo. Deve ser resubmetido como um novo modelo (frequentemente recategorizado) se quiser voltar a usar o conteúdo.
  </Step>
</Steps>

## Classificação de qualidade

Uma vez aprovado, cada modelo constrói a sua própria classificação de qualidade — separada da [classificação de qualidade do número de telefone](/pt/meta/quality-score). A classificação ao nível do modelo usa a mesma escala Verde/Amarelo/Vermelho e é impulsionada sobretudo por:

* Taxa de bloqueio entre destinatários
* Frequência de ações "Reportar" no WhatsApp
* Baixo envolvimento sustentado (sem respostas, sem cliques em links)

Classificações de modelo Amarelo e Vermelho podem fazer com que a Meta pause o modelo mesmo que a classificação do número de telefone esteja Verde. Observe a qualidade do modelo em **Flowella → Modelos** ao lado da classificação ao nível do número.

## Tempo-de-vida (TTL)

Os modelos podem ter um **tempo-de-vida** que controla quanto tempo a Meta tentará entregar antes de desistir. Útil para envios sensíveis ao tempo, como convites para saldos-relâmpago.

* **Predefinição:** 30 dias para a maioria dos modelos.
* **Modelos OTP / autenticação:** muito mais curto (alguns minutos por defeito), uma vez que os códigos não têm valor depois de expirados.
* **TTL personalizado:** pode ser definido por envio para alguns tipos de modelo.

Se um modelo expira antes da entrega (telemóvel do destinatário offline, conta pausada, etc.), conta como envio para faturação, mas nunca chega ao cliente.

## Motivos comuns de rejeição

* **Conteúdo promocional submetido como Utility.** Volte a submeter como Marketing.
* **Amostras de variáveis que não correspondem ao corpo** — por exemplo, amostras que contêm links que o corpo não justifica.
* **Corpo ou texto de cabeçalho que parece spam** — capitalização excessiva, "Clique aqui", "Grátis!!!", múltiplos pontos de exclamação.
* **URLs de cabeçalho de media partidos ou inalcançáveis.**
* **Texto de rodapé que contradiz o corpo.**
* **Modelos genéricos** que poderiam ser enviados por qualquer pessoa — `Olá {{1}}, oferta especial para si` sem especificidades é demasiado genérico para aprovação de marketing.
* **Variáveis no contexto errado** — usar uma variável num lugar que a Meta não permite (por exemplo, alguns tipos de botão).
* **O nome de exibição não corresponde à marca** do conteúdo do modelo. Se o nome de exibição da WABA é "Acme" e o modelo promove "Beta Co", será rejeitado.

<Tip>
  Edite uma cópia de um modelo APROVADO em vez do original, para manter uma versão a funcionar enquanto a Meta revê as alterações. **Modelos → Duplicar** do Flowella faz isso por si, e copia a media do cabeçalho (IMAGE, VIDEO ou DOCUMENT) e o **Nome de ficheiro do documento** para o novo rascunho para não ter de fazer novo upload antes de publicar. Se o Flowella não conseguir copiar a media (por exemplo quando o URL de amostra original está inalcançável), o editor mostra um aviso e bloqueia a publicação até refazer o upload do ficheiro.
</Tip>

## Guias relacionados

* [Modelos](/pt/app/templates) — o passo a passo de construir um modelo
* [Cabeçalhos de media](/pt/app/media-in-template-headers) — referência de formato de media
* [Modelo rejeitado](/pt/troubleshooting/template-rejected) — diagnosticar rejeições
* [Pontuação de qualidade](/pt/meta/quality-score) — como a qualidade do número de telefone interage com a qualidade do modelo
* [Limites de mensagens](/pt/meta/messaging-limits) — o sistema de níveis que restringe quantos modelos pode enviar


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.