Criar template HSM

Template HSM (Highly Structured Message) é o formato oficial Meta pra enviar mensagem no WhatsApp fora da janela de 24h. Cada template precisa ser submetido pra aprovação antes de poder ser usado, demora ~24-72h, e tem regras estritas de formato e categoria. Esse artigo cobre o wizard de criação no Syncro.

Pré-requisitos

• Permissão admin. Veja Conectar WhatsApp Cloud API.

• Plano com cota de templates disponível (max_whatsapp_templates).

• Feature flag whatsapp_cloud_api ativa pro tenant.

Acessar templates

1. Menu lateral → Configurações → Templates WhatsApp.
2. Página /configuracoes/whatsapp-templates abre com lista cadastrada.
3. Botão Criar template no canto superior direito.

Layout do wizard (70/30)

A tela de criação tem 2 colunas:

• Esquerda (70%) — formulário com campos.
• Direita (30%) — preview iPhone ao vivo, simulando como o cliente vai ver no WhatsApp. Atualiza em tempo real conforme você preenche.

Campos do template

1. Instância WhatsApp (obrigatório)

Dropdown lista todas instâncias Cloud API ativas do tenant.

⚠️ Atenção: cada template é vinculado a uma WABA (Business Account ID). Templates não compartilham entre instâncias. Se você tem 2 números, vai precisar criar template em cada um separadamente.

2. Nome (obrigatório, max 64 chars)

Identificador interno do template. Regras Meta:

• Apenas letras minúsculas, números e underscore: ^[a-z0-9_]{1,64}$.
• Sem acentos, sem espaços, sem hífen.
• Máximo 64 caracteres.

✅ Bons nomes: lembrete_consulta, boas_vindas_compra, codigo_otp, confirmacao_pedido. ❌ Ruins: Lembrete Consulta, lembrete-consulta, lembreteConsulta.

3. Idioma (obrigatório)

Dropdown com idiomas suportados pela Meta:

• pt_BR — Português (Brasil) ✅ mais comum.
• en_US — Inglês (EUA).
• es_ES, es_MX — Espanhol.
• ~80 outros.

💡 Dica: pra atender clientes em vários idiomas, crie um template por idioma com o mesmo nome: boas_vindas em pt_BR, boas_vindas em en_US. Meta trata como diferentes mas relacionados.

4. Categoria (obrigatório)

3 cards selecionáveis. Esta escolha é crítica pro custo e aprovação:

UTILITY (Utilidade)

Mensagens transacionais sobre algo que o cliente solicitou:

• Confirmação de pedido / agendamento.
• Atualização de envio.
• Lembrete de consulta.
• Notificação de fatura paga.

✅ Mais barato (~50% do custo de Marketing). ✅ Aprovação rápida (geralmente <24h). ⚠️ Meta pode reclassificar automaticamente pra MARKETING se conteúdo for promocional. Veja Aprovação Meta e categoria.

MARKETING

Mensagens promocionais:

• Ofertas, descontos.
• Lançamento de produto.
• Newsletter.
• Reativação de cliente inativo.

⚠️ Mais caro (~2x UTILITY). ⚠️ Aprovação pode levar mais tempo (24-72h). ⚠️ Cliente precisa ter opt-in explícito (Meta verifica).

AUTHENTICATION

Mensagens de OTP (códigos de verificação):

• Código de login.
• Confirmação 2FA.

✅ Mais barato ainda (categoria mais barata da Meta). ⚠️ Formato muito restrito — Meta aceita apenas variantes específicas. ⚠️ Body fixo: "Your verification code is {{1}}." (ou variantes traduzidas). Não permite texto customizado.

5. Header (opcional)

Cabeçalho do template. Tipos:

• Sem header — template começa direto no body.
• Texto — header de até 60 chars, pode ter 1 variável {{1}}.
• Imagem — JPG/PNG (max 5MB).
• Vídeo — MP4 (max 16MB).
• Documento — PDF (max 100MB).

Header com mídia

1. Selecione o tipo (Imagem/Vídeo/Documento).
2. Aparece dropzone pra upload.
3. Faça upload do arquivo de exemplo (Meta usa pra revisar).
4. Sistema faz upload resumable pra Meta (2 chamadas HTTP), recebe handle (formato 4:...).
5. Handle vai junto no submit do template.

⚠️ Atenção: o arquivo no upload é só exemplo. Quando você envia o template real depois, pode trocar pela mídia real (foto do produto X comprado, etc).

6. Body (obrigatório, max 1024 chars)

Texto principal da mensagem. Suporta:

• Texto livre com formatação WhatsApp (*bold*, _italic_, ~strike~, `mono`).
• Variáveis numeradas sequenciais: {{1}}, {{2}}, {{3}}, etc.

Botões de variáveis

UI tem botões de atalho pra inserir variáveis com labels amigáveis:

• Nome do cliente → insere {{1}} + label "Nome do cliente".
• Data → insere {{N}} + label "Data".
• Hora, Empresa, Valor, Código, Link, Outro.

Cada clique adiciona próximo número sequencial.

⚠️ Atenção: variáveis devem ser sequenciais sem pular. Se você tem {{1}} e {{3}} mas não {{2}}, Meta rejeita. Sistema valida no submit.

Exemplo de body

Olá {{1}}!

Sua consulta está agendada pra {{2}} às {{3}}.

Endereço: {{4}}

Em caso de dúvidas, responda esta mensagem.

Variáveis: 1=nome, 2=data, 3=hora, 4=endereço.

7. Sample Variables (obrigatório se body tem variáveis)

Pra cada variável {{N}}, você fornece exemplo realista que a Meta usa pra revisar.

Pra {{1}}=nome: "João Silva". Pra {{2}}=data: "15/04/2026". Pra {{3}}=hora: "14:30".

Sistema gera inputs dinâmicos conforme variáveis são adicionadas.

8. Footer (opcional, max 60 chars)

Rodapé curto, sem variáveis.

Ex: "Resposta automática. Não responda.", "Atendimento Seg-Sex 9-18h.".

9. Botões (opcional, max 10)

Botões interativos abaixo da mensagem. 4 tipos:

Quick Reply (max 3)

Botão de resposta rápida. Cliente clica → manda texto de volta.

{ "type": "QUICK_REPLY", "text": "Sim" }
{ "type": "QUICK_REPLY", "text": "Não" }

URL

Botão que abre link no navegador.

{ "type": "URL", "text": "Ver pedido", "url": "https://app.com/pedidos/{{1}}" }

URL pode conter 1 variável.

Phone

Botão que liga pro número.

{ "type": "PHONE_NUMBER", "text": "Falar com vendas", "phone_number": "+5511987654321" }

Copy Code (OTP)

Cliente clica → copia código pro clipboard.

{ "type": "COPY_CODE", "example": "X7Y9KL" }

💡 Dica: máximo 10 botões total, mas só 3 podem ser Quick Reply. Os outros 7 podem ser URL/Phone/Copy.

Validações antes de submeter

Sistema valida localmente antes de enviar pra Meta:

• ✅ Nome em snake_case.
• ✅ Variáveis sequenciais (1, 2, 3 sem pular).
• ✅ Sample variables preenchidos pra cada {{N}}.
• ✅ Categoria selecionada.
• ✅ Body presente.
• ✅ Combinação (instance, name, language) única no tenant.

Se falha, mensagem vermelha aparece no topo. Corrija antes de continuar.

Submeter pra aprovação

1. Após preencher tudo, clique em Enviar pra análise da Meta.
2. Sistema:

• Valida localmente.
• Faz upload de mídia (se houver) via resumable.
• Monta JSON components no formato Meta.
• Faz POST /{waba_id}/message_templates na Graph API.
• Recebe meta_template_id da Meta.
• Cria registro local com status='PENDING' + last_synced_at=now.

3. Toast: "Template enviado pra análise da Meta. Aprovação leva 24 a 72h.".
4. Redireciona pra lista de templates.
5. Status na lista: Em análise (badge amarelo).

O que acontece após submit

A Meta avalia em ~24-72h:

• ✅ Aprovado → status muda pra APPROVED. Pode usar pra enviar mensagens.
• ❌ Rejeitado → status REJECTED + rejected_reason preenchido. Veja motivo na página show.
• ⏳ Em análise → continua PENDING até Meta decidir.

Sync diário (whatsapp:sync-templates cron 04:00) atualiza status. Você não precisa fazer nada — só esperar e checar.

Veja Sincronizar status de templates.

Página show (detalhes)

Após criar, clique no nome do template na lista pra ver:

• Header com status badge.
• Info card (esquerda): idioma, categoria, instância, quality_rating, Meta ID, last synced.
• Preview iPhone (direita, sticky): como vai aparecer pro cliente.
• Box vermelho (se REJECTED): motivo da rejeição.
• Botão Excluir.

Tipos de template úteis

Lembrete de consulta (UTILITY)

Body:
Olá {{1}}!

Lembrando que você tem consulta agendada pra {{2}} às {{3}}.

Endereço: {{4}}

Confirma sua presença?

Buttons:
- QUICK_REPLY: "Sim, confirmo"
- QUICK_REPLY: "Preciso remarcar"

Boas-vindas após compra (UTILITY)

Header (Imagem): foto do produto
Body:
Oi {{1}}! 🎉

Seu pedido #{{2}} foi confirmado e está sendo preparado.

Previsão de entrega: {{3}}.

Buttons:
- URL: "Acompanhar pedido" → https://meusite.com/pedidos/{{1}}

Black Friday (MARKETING)

Header (Imagem): banner de Black Friday
Body:
{{1}}, sua oferta exclusiva chegou! 🛍️

20% OFF em toda a loja até {{2}}.

Buttons:
- URL: "Comprar agora" → https://meusite.com/blackfriday
- QUICK_REPLY: "Tirar do mailing"

OTP (AUTHENTICATION)

Body:
Your code is {{1}}. (Meta força esse texto fixo + variantes)

Buttons:
- COPY_CODE: example "ABC123"

Boas práticas

1. Nome descritivo

Nome do template aparece em automações, follow-ups, modal de envio. Use algo claro:

✅ lembrete_consulta_24h ❌ template1 ou t_lc_24h

2. Categoria certa = custo certo

UTILITY é metade do preço de MARKETING. Se sua mensagem é transacional (ligada a algo que o cliente fez), não use MARKETING — vai pagar a mais.

3. Sample variables realistas

Meta avalia o template baseado nos exemplos. Se você bota {{1}}=teste123 em um template de cobrança, pode ser rejeitado por parecer falso.

4. Body objetivo

Templates longos demais convertem mal. Mensagem de 1024 chars cabe muito — mas mensagem de 200-400 chars performa melhor.

5. Sempre teste em ambiente real

Após aprovar, envie pra seu próprio número primeiro. Confira que aparece corretamente — botões funcionam, variáveis preencheram certo.

6. Templates duplicados

Crie variações pra A/B test:

• boas_vindas_v1 (assertivo).
• boas_vindas_v2 (amigável).
• Compare conversão.

Excluir template

1. Página show ou lista → botão Excluir.
2. Confirme.
3. Sistema:

• Faz DELETE /{template_id} na Meta (idempotente — se já não existe, ignora).
• Apaga local.

⚠️ Atenção: ação irreversível. Se você usa o template em automações ou follow-ups, esses fluxos vão falhar ao tentar usar template inexistente. Revise antes de excluir.

Limites de plano

Plano	max_whatsapp_templates
Trial	0 (não disponível)
Starter	5
Growth	25
Scale	100+

Erros comuns

"Nome inválido — use snake_case"

Você usou letra maiúscula, espaço, hífen ou acento. Use só [a-z0-9_].

"Variável fora de sequência"

Você tem {{1}} e {{3}} mas não {{2}}. Renumere.

"Já existe template com esse nome+idioma"

Combinação (instance, name, language) deve ser única. Use nome diferente OU idioma diferente.

"Falha ao fazer upload de mídia"

Mídia muito grande, formato errado, ou Meta rejeitou. Verifique limites (Imagem 5MB, Vídeo 16MB, Documento 100MB).

Template ficou em PENDING por dias

• Meta pode demorar até 72h.
• Se passar disso, abra suporte da Meta no Business Manager.
• Sistema sincroniza diariamente — você verá assim que mudar.

Próximos passos

• Pra entender aprovação Meta + reclassificação, veja Aprovação Meta e categoria.
• Pra enviar templates aprovados, veja Enviar template.

Artigos relacionados

• Aprovação Meta e categoria
• Enviar template
• Sincronizar status de templates
• Conectar WhatsApp Cloud API
• Janela 24h explicada