Sincronizar status de templates

Após você criar template HSM, a Meta é a fonte da verdade — eles aprovam, rejeitam, reclassificam categoria, atualizam quality rating, e podem deletar templates por baixa performance. O Syncro sincroniza esses dados diariamente via cron + permite sync manual sob demanda. Esse artigo cobre como funciona, quando usar, e como diagnosticar problemas.

Pré-requisitos

• Templates submetidos pra Meta. Veja Criar template HSM.
• Permissão admin pra disparar sync manual.

Por que sincronizar

Meta pode mudar status do template a qualquer momento sem notificar:

• ✅ Templates PENDING viram APPROVED ou REJECTED.
• ⚠️ APPROVED pode virar PAUSED (baixa qualidade).
• ⚠️ PAUSED pode virar DISABLED (após pause prolongado).
• 🔄 Categoria pode mudar (UTILITY→MARKETING reclassificação automática).
• 📊 quality_rating é atualizado conforme cliente engaja/ignora.

Sem sync, sistema fica com info desatualizada. Você pode:

• Tentar enviar template já DISABLED → erro Meta.
• Ver categoria errada → estimar custo errado.
• Não notar quality rating caindo até tarde demais.

Sync automático (cron diário)

Quando roda

Todos os dias às 04:00 (timezone America/Sao_Paulo).

Roda sem intervenção — você não precisa configurar nada após criar templates.

O que faz

Pra cada instância Cloud API ativa de cada tenant:

1. Chama Graph API: GET /{waba_id}/message_templates (paginado, até 20 páginas).
2. Pra cada template remoto recebido:

• Extrai dados: name, language, status, category, components, quality_score, rejected_reason.
• Busca template local por meta_template_id:
• Existe local: atualiza campos que mudaram. Loga reclassificação se categoria mudou.
• Não existe: cria registro local (caso template tenha sido criado direto na Meta, fora do Syncro).

3. Pra cada template local que não veio da Meta (Meta deletou):

• Remove local (cascata).

4. Atualiza last_synced_at = now em cada template tocado.
5. Loga resumo no canal whatsapp.log.

Output esperado

Logs mostram:

WhatsappTemplate sync started — tenant_id=12, instance_id=5
Templates found in Meta: 8
- created: 0
- updated: 5 (status changed: 1 PENDING→APPROVED, 1 APPROVED→PAUSED)
- removed: 1 (deleted from Meta)
- reclassified: 1 (template "promo_xx": UTILITY → MARKETING)
WhatsappTemplate sync done.

Sync manual

Quando usar

• Você submeteu template e quer ver status agora (sem esperar 04:00).
• Você fez reclassificação na Meta e quer atualizar.
• Você deletou template direto na Meta e quer remover do Syncro.
• Suspeita que dados estão desatualizados.

Como fazer

1. Vá em /configuracoes/whatsapp-templates.
2. Botão Sincronizar com Meta no canto superior direito.
3. Clique.
4. Loader aparece (~2-10 segundos dependendo de número de templates).
5. Toast: "Sincronização concluída.".
6. Página recarrega com dados atualizados.

Múltiplas instâncias

Se você tem mais de 1 número Cloud API:

• Botão sincroniza todas as instâncias de uma vez.
• Loop por instância → chama Graph API de cada WABA → atualiza local.

Sync via comando (CLI)

Pra ambiente de produção/QA, sysadmins podem rodar manualmente:

Útil pra debug ou migração de tenants.

O que é sincronizado

Pra cada template, sistema atualiza:

Campo	Origem Meta	Atualizado quando
status	template.status	A cada sync
category	template.category	A cada sync (incluindo reclassificação)
components	template.components	A cada sync
quality_rating	template.quality_score.score	A cada sync
rejected_reason	template.rejected_reason	Se REJECTED
last_synced_at	—	A cada sync (timestamp local)

Detecção de reclassificação

Quando categoria muda na Meta:

1. Sistema compara category local vs Meta.
2. Se diferentes, loga warning em storage/logs/whatsapp.log:

[2026-04-30 04:00:15] whatsapp.WARNING: WhatsappTemplate: categoria re-classificada pela Meta
{
"template_id": 42,
"name": "promo_blackfriday",
"language": "pt_BR",
"tenant_id": 12,
"from": "UTILITY",
"to": "MARKETING"
}

3. Atualiza category local pra refletir Meta.
4. Página show do template mostra info box explicando que reclassificação ocorreu.

Veja Aprovação Meta e categoria pra detalhes.

Templates removidos da Meta

Se template sumiu da Meta entre syncs:

• Meta deletou (admin do Business Manager apagou ou Meta desativou permanentemente).
• Sistema remove local automaticamente.
• Log: Template "{name}" removido — não retornou da Meta.

⚠️ Atenção: se você tem automações ou follow-ups que apontam pro template removido, vão falhar silenciosamente. Revise periodicamente.

Templates criados direto na Meta

Você pode criar templates fora do Syncro, direto no Business Manager. Sync detecta e adiciona local.

Por que pode acontecer

• Equipe Meta criou pra você (parceria oficial).
• Você criou via Graph API custom em outro sistema.
• Migração de outro provedor pra Syncro.

Como aparece

• Sync cria registro local com:
• tenant_id = tenant da instância.
• whatsapp_instance_id = instância correspondente.
• meta_template_id = ID retornado pela Meta.
• sample_variables = NULL (não vieram do Syncro).
• Você pode editar sample_variables na UI pra dar labels amigáveis às variáveis (UX no modal de envio).

Conflitos e edge cases

Template aprovado mas no Syncro continua PENDING

Causa: sync ainda não rodou. Roda às 04:00 ou faça sync manual.

Template rejeitado mas não vejo motivo

rejected_reason é populado só quando vem da Meta. Se template foi rejeitado antes do primeiro sync, motivo não está no Syncro.

Solução: vá no Business Manager Meta → templates → veja motivo lá.

Template diferente entre Syncro e Meta

Sync atualiza Syncro com Meta — Meta sempre vence.

Se você editou template no Business Manager (ex: mudou body), próximo sync atualiza local com novo body.

Template aparece duplicado

Possível bug se sync rodou parcialmente. Solução:

1. Identifique o duplicado (mesmo name+language).
2. Delete o mais antigo (sem meta_template_id se for inconsistente).
3. Faça sync manual pra normalizar.

Sync falha com erro 400 da Meta

• Token expirado (system_user_token inválido) — reconecte instância.
• WABA bloqueada pela Meta — verifique no Business Manager.
• Rate limit Meta — aguarde 1h e tente novamente.

Erro completo aparece em whatsapp.log.

Frequência customizada

O cron padrão é diário 04:00. Pra mudar:

1. Edite routes/console.php ou bootstrap/app.php:

$schedule->command('whatsapp:sync-templates')
->everyFourHours // a cada 4 horas
->name('sync-whatsapp-templates')
->onOneServer;

2. Reinicie scheduler.

⚠️ Atenção: rate limit Meta pode ser atingido se sync muito frequente. 24h é suficiente pra maioria dos casos.

Logs e troubleshooting

Ver logs de sync

Procure linhas com WhatsappTemplate ou sync.

Histórico de sync

Página show de cada template mostra last_synced_at:

"Última sincronização: 30/04/2026 04:00"

Se está muito antiga (> 2 dias), algo travou no cron.

Diagnosticar cron parado

1. Verifique se scheduler service está rodando (docker service ls).
2. Veja last successful run em logs.
3. Se manual funciona mas automático não, problema é no scheduler — reinicie.

Estratégia de monitoramento

1. Verifique semanalmente

• Status dos templates importantes (não viraram PAUSED).
• Quality rating (não caiu pra LOW).
• Reclassificações inesperadas.

2. Alertas em logs

Se você tem agregador de logs (Sentry, Logtail), filtre por:

• WhatsappTemplate.*reclassified — reclassificações.
• WhatsappTemplate.*REJECTED — rejeições novas.
• WhatsappTemplate.*PAUSED — pauses.

3. Use template UTILITY como default

Mesmo quando categoria muda, UTILITY tem mais chance de manter aprovação. Crie versões UTILITY dos seus templates importantes.

Erros comuns

"Sync demorou e não atualizou nada"

• Verifique last_synced_at — se mudou, sync rodou OK, só não tinha mudança.
• Se não mudou, sync falhou — veja logs.

"Template novo no Meta não apareceu no Syncro"

• Sync diário (04:00) cobre — aguarde até manhã.
• OU sync manual agora pelo botão.

"last_synced_at em todos templates está null"

Sync nunca rodou pra essa instância. Possíveis causas:

• Instância não tem system_user_token válido.
• WABA ID não preenchido na instância.
• Cron não foi rodado ainda.

Solução: faça sync manual pelo botão ou comando, veja erros.

"Reclassificação aconteceu mas Syncro mostra categoria antiga"

Cache. Aguarde sync ou force manual.

Próximos passos

• Pra criar mais templates, veja Criar template HSM.
• Pra entender aprovação Meta, veja Aprovação Meta e categoria.

Artigos relacionados

• Criar template HSM
• Aprovação Meta e categoria
• Enviar template
• Conectar WhatsApp Cloud API