Enviar template

Template HSM aprovado é inútil se você não envia. O Syncro permite envio em 4 caminhos: manual no chat, action de automação, follow-up smart de IA e sequência de nurturing. Cada um com cenário próprio. Esse artigo cobre todos.

Pré-requisitos

• Template criado e APPROVED. Veja Criar template HSM.
• Instância WhatsApp Cloud API conectada na qual o template foi aprovado.
• Permissão pra enviar mensagens (admin/manager — viewer não envia).

Caminho 1 — Envio manual no chat

Quando usar

• Cliente parou de responder e janela 24h fechou — você quer reabrir.
• Quer enviar promoção pontual pra um lead específico.
• Cliente novo (nunca falou) — primeira mensagem oficial.

Como enviar

1. Vá em /chats.
2. Abra a conversa do cliente.
3. Veja o status da janela:

• Se aberta (cliente respondeu nas últimas 24h): input de texto livre disponível.
• Se fechada: input de texto desabilitado com aviso "A janela de 24h dessa conversa foi fechada. Use um template aprovado pra retomar.".

4. Clique no botão + (canto inferior do input) → Template no menu.
5. Modal "Enviar template" abre.

Modal de seleção

Modal mostra:

• Lista de templates APPROVED da mesma instância da conversa.
• Filtro/busca por nome.
• Categoria (badge: UTILITY / MARKETING / AUTHENTICATION).
• Idioma.
• Preview iPhone (atualiza ao selecionar).

Preencher variáveis

Após selecionar template:

• Inputs aparecem pra cada variável {{1}}, {{2}}, etc.
• Cada input tem label amigável (ex: "Nome do cliente", "Data") — definido na criação do template.
• Preview à direita atualiza em tempo real conforme você digita.

Exemplo — template "lembrete_consulta":

{{1}} — Nome do cliente: João
{{2}} — Data: 15/04/2026
{{3}} — Hora: 14:30
{{4}} — Endereço: Rua A, 123

Header com mídia (se template tem)

Se template tem header de imagem/vídeo/documento, modal mostra:

• Upload pra enviar mídia real (sobrescreve o exemplo).
• OU input de URL externa.

Exemplo: template boas_vindas_compra com header de imagem → você anexa foto do produto comprado específico.

Enviar

1. Verifique preview final.
2. Clique em Enviar template.
3. Sistema:

• Monta payload com template name + language + components + variables.
• Faz POST /messages na Graph API.
• Salva WhatsappMessage com type=template.
• Atualiza last_message_at da conversa.
• Reabre janela 24h (cliente pode responder texto livre por 24h).

4. Toast: "Template enviado.".
5. Bolha aparece no chat.

💡 Dica: enviar template abre janela 24h automaticamente. Cliente vai poder responder texto livre. Aproveite essa janela pra continuar conversa via texto normal (mais barato que template).

Caminho 2 — Automação (action send_whatsapp_template)

Quando usar

• Disparo automático em trigger (lead criado, lead ganho, conversa fechada, etc).
• Mensagem programática baseada em condição.

Configurar

1. Vá em /configuracoes/automacoes.
2. Crie ou edite uma automação.
3. Sidebar de Actions → Enviar template WhatsApp (send_whatsapp_template).

⚠️ Atenção: action só aparece se tenant tem instância Cloud API conectada e templates APPROVED.

4. Configure:

• Template: dropdown lista templates APPROVED.
• Variáveis: pra cada {{N}}, defina valor — pode ser:
• Estático: "João Silva".
• Dinâmico: {{lead.name}}, {{lead.email}}, {{lead.value}}, {{custom_field.X}}, etc.
• Header media (se aplicável): URL pública.

5. Salve.

Exemplo prático

Trigger: Lead movido pra etapa "Negociação". Action: Enviar template proposta_enviada com:

• {{1}} = {{lead.name}} → "Maria"
• {{2}} = {{lead.value}} → "R$ 5.000"
• Header URL = {{lead.proposal_pdf_url}}

Quando lead chega em "Negociação", template é enviado automaticamente com nome + valor preenchidos + PDF anexado.

Veja Criar automação.

Caminho 3 — Follow-up Smart de IA

Quando usar

Você tem agente IA atendendo conversas. Cliente para de responder. Janela 24h fecha. IA quer reativar o cliente.

Estratégias do agente IA

Cada agente IA tem coluna followup_strategy:

Estratégia	Comportamento
off	Nunca faz follow-up
smart (default)	Se janela aberta: texto livre. Se fechada: template fallback OU skip se sem template
template	Sempre usa template, mesmo dentro da janela

Configurar template fallback

1. Em /ia/agentes, edite o agente.
2. Aba Follow-up.
3. Selecione followup_strategy = smart ou template.
4. Campo Template fallback: dropdown lista templates APPROVED da instância configurada.
5. Salve.

Como funciona

Cron ai:followup (a cada 10 min) varre conversas com IA atribuída e detecta:

• Cliente parou de responder por X horas (configurável no agente).
• IA decide: hora de reativar.
• Verifica janela 24h via ConversationWindowChecker::isOpen($conv):
• Aberta + estratégia smart: envia texto livre normal.
• Fechada + estratégia smart + template fallback configurado: envia template.
• Fechada + estratégia smart SEM template: skip (registra skip_reasons.window_closed_no_template). Poupa custo.
• Estratégia template: sempre envia template, independente da janela.

Exemplo

Agente Camila com:

• followup_strategy='smart'.
• followup_template_id = template volte_falar_conosco.

Cliente João parou de responder há 30h (janela fechou). IA detecta. Envia template volte_falar_conosco com {{1}}=João. Cliente recebe → responde → janela reabre → IA continua atendimento via texto livre normal.

Veja Follow-up smart, template, off.

Caminho 4 — Sequência de nurturing

Quando usar

Você tem sequência multi-step com mensagens espaçadas. Algum step pode cair fora da janela 24h.

Configurar fallback no step

1. Vá em /configuracoes/sequencias.
2. Edite a sequência.
3. Edite o step que envia mensagem.
4. Campo Template fallback (fallback_template_id): dropdown.
5. Salve.

Como funciona

Quando o step executa:

• Verifica janela 24h.
• Aberta: envia texto livre.
• Fechada + template fallback: envia template.
• Fechada + sem template: skip + log.

Exemplo

Sequência "Recuperação de carrinho":

Step 1 (1h após abandono): mensagem texto "Você esqueceu algo?"
Step 2 (24h): texto "Ainda interessado?"
Step 3 (72h): TEMPLATE "carrinho_abandonado" (porque janela já fechou)

Sem template no step 3, sequência travaria. Com fallback, cliente recebe lembrete oficial Meta.

Veja Passos: mensagem e delay.

Detecção de janela 24h

A regra Meta:

• Cada mensagem inbound do cliente abre/renova janela de 24h.
• Dentro: você pode mandar texto livre, mídia, qualquer coisa.
• Fora: só template HSM.
• Texto livre fora da janela: Meta retorna erro 470/132xxx.

Sistema detecta via ConversationWindowChecker::isOpen($conv):

• Calcula tempo desde última mensagem inbound.
• Retorna true se < 24h.
• Retorna false se ≥ 24h.

QR Code não tem janela 24h (API não-oficial — não respeita regra Meta). isOpen sempre retorna true pra QR Code.

Veja Janela 24h explicada.

Custo de envio

Meta cobra por conversa iniciada (não por mensagem). Início = primeiro template fora da janela.

Categoria	Custo aprox (Brasil, 2026)
UTILITY	~R$ 0,03
MARKETING	~R$ 0,06
AUTHENTICATION	~R$ 0,02
Service (resposta dentro de janela)	Grátis

Após enviar template, próximas mensagens dentro de 24h são grátis.

💡 Dica: pra economizar, reabra janela com template UTILITY uma vez, depois converse normal por 24h sem custo extra.

Veja Janela 24h explicada pra detalhes de billing.

Quem pode enviar

Role	Manual no chat	Automação	Follow-up IA	Sequência
admin	✅	✅ Cria/edita	✅ Configura agente	✅
manager	✅	✅ Cria/edita	✅	✅
viewer	❌	❌ Só vê	❌	❌

Logs e tracking

No chat

Mensagem template aparece como bolha normal, com:

• Texto interpolado.
• Header com mídia (se houver).
• Botões.

Badge na bolha mostra Template (cinza).

No backend

Cada envio cria WhatsappMessage com:

• type='template'.
• body = texto renderizado.
• cloud_message_id da Meta.
• sent_by = human (manual), automation, followup ou nurture.

Você pode buscar histórico em /contatos/{lead} → Mensagens.

Erros comuns

"Template não aparece no modal"

• Status precisa ser APPROVED (não PENDING/REJECTED).
• Mesma instância da conversa.
• Idioma geralmente pt_BR — outros idiomas podem aparecer dependendo do template.

"Erro ao enviar template" no chat

• Verifique cloud_message_id retornou erro Meta.
• Pode ser número inválido, opt-out global, quality rating LOW.
• Logs em whatsapp.log mostram erro detalhado.

"Template enviou mas cliente não recebeu"

• Cliente bloqueou seu número.
• Cliente ativou opt-out global de mensagens business.
• Atrasos eventual da Meta — aguarde alguns minutos.

"Variável não substituiu, ficou {{1}} literal"

• Você não preencheu o input da variável no modal.
• Em automação: variável dinâmica ({{lead.name}}) não resolveu — verifique se lead tem o campo.

"Action send_whatsapp_template não aparece na automação"

• Tenant não tem instância Cloud API conectada.
• Tenant não tem template APPROVED.
• Feature flag whatsapp_cloud_api desativada.

Boas práticas

1. Template objetivo

Cliente recebe — entende em 5 segundos qual a ação esperada.

2. Reabra janela com UTILITY (mais barato)

Pra retomar conversa, use template UTILITY de boas-vindas/lembrete (não MARKETING).

3. Não abuse de MARKETING

Cliente recebendo 5 templates promocionais por mês vai bloquear. Quality rating cai.

4. Use header com mídia quando faz sentido

Foto do produto, voucher, fatura PDF — aumentam engajamento.

5. Botões interativos > links em texto

Botão URL converte mais que link https://... no body.

Próximos passos

• Pra entender sync de status, veja Sincronizar status de templates.
• Pra entender janela 24h, veja Janela 24h explicada.

Artigos relacionados

• Criar template HSM
• Aprovação Meta e categoria
• Sincronizar status de templates
• Follow-up smart, template, off
• Janela 24h explicada