Templates
Templates são modelos de mensagem reutilizáveis. Eles servem para dois propósitos:- Operação manual — operadores inserem rapidamente respostas padronizadas no Chat.
- 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)
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 |
Em instâncias Meta Oficial, só templates Aprovados podem ser enviados via API ou agendamento.
Em instâncias API Business (Z-API), o template é enviado como texto livre — não há aprovação.
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 |
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.
variables: { "1": "João", "2": "12345" }.
NAMED ({{nome}}, {{pedido}})
Variáveis com nomes descritivos — mais legível e mais robusto a alterações.
variables: { "nome": "João", "pedido": "12345" }.
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.nametelefone—contacts.phone- Outros campos do contato disponíveis no escopo da instância
Criar um template
Informações básicas
- Nome — identificador interno (ex:
confirmacao_agendamento) - Categoria — Utilidade, Marketing ou Autenticação
- Idioma —
pt_BR,en_US, etc.
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.
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_idse a Meta tiver migrado IDs
Enviar via API
Use o endpoint dedicado, que detecta automaticamente o provedor da instância (Meta Oficial ou API Business): POST /send-template-message → Cabeçalho estático, rodapé e botões fixos vão automaticamente — você só passa as variáveis dinâmicas no campovariables.