Templates: sincronize, armazene e envie com segurança

O que é um template

Templates são modelos de mensagem aprovados pela Meta. Eles são usados para iniciar ou retomar conversas fora da janela de atendimento, além de casos de autenticação, utilidade e marketing. O template pertence à WABA, tem nome, idioma, categoria, componentes e status próprios.

O que a HookCloud já administra — e o que fica com você

Para consultar templates, você usa o WABA ID e o Meta Access Token correspondentes ao número conectado. O token deve ficar no servidor. O navegador, o chat da comunidade e o código público do site não são locais seguros para armazená-lo.

GET oficial para listar templates

A listagem é feita na Graph API com o WABA ID. Use uma versão configurável da API; o exemplo abaixo usa a versão adotada atualmente pelo projeto.

curl -G \
  "https://graph.facebook.com/v25.0/WABA_ID/message_templates" \
  -H "Authorization: Bearer META_ACCESS_TOKEN" \
  --data-urlencode "fields=id,name,language,status,category,components,quality_score,rejected_reason,last_updated_time" \
  --data-urlencode "limit=100"

Resposta e paginação

A resposta contém data e, quando houver mais resultados, um objeto paging com cursores e uma URL next. Continue apenas enquanto paging.next existir.

{
  "data": [
    {
      "id": "1234567890",
      "name": "confirmacao_agendamento",
      "language": "pt_BR",
      "status": "APPROVED",
      "category": "UTILITY",
      "components": []
    }
  ],
  "paging": {
    "cursors": { "before": "...", "after": "..." },
    "next": "https://graph.facebook.com/..."
  }
}

Uma página adicional é uma nova chamada. Por isso, uma tela que repete a sincronização completa a cada abertura multiplica rapidamente o consumo da WABA.

Como armazenar os templates no seu sistema

Use uma tabela local por workspace/WABA. Um modelo mínimo:

create table whatsapp_message_templates (
  id uuid primary key default gen_random_uuid(),
  workspace_id uuid not null,
  waba_id text not null,
  meta_template_id text,
  name text not null,
  language text not null,
  category text,
  status text not null,
  quality_score text,
  rejected_reason text,
  components jsonb not null default '[]'::jsonb,
  meta_last_updated_at timestamptz,
  last_synced_at timestamptz not null default now(),
  deleted_at timestamptz,
  unique (waba_id, name, language)
);

• Use meta_template_id como referência externa quando disponível.
• Mantenha unicidade por WABA + nome + idioma.
• Guarde components como JSON para reconstruir parâmetros de header, body e botões.
• Nunca salve o access token na mesma tabela de uso comum dos templates.
• Marque como ausente/deletado somente depois de uma sincronização completa e bem-sucedida; uma página incompleta não prova exclusão.

Fluxo recomendado de sincronização

Exemplo de sincronização no backend

Exemplo simplificado em TypeScript. O método upsertTemplate representa a gravação no seu banco.

type MetaTemplatePage = {
  data: Array<{
    id: string;
    name: string;
    language: string;
    status: string;
    category?: string;
    components?: unknown[];
    quality_score?: unknown;
    rejected_reason?: string;
    last_updated_time?: string;
  }>;
  paging?: { next?: string };
};

async function syncTemplates(wabaId: string, accessToken: string) {
  const fields = [
    'id','name','language','status','category','components',
    'quality_score','rejected_reason','last_updated_time'
  ].join(',');

  let next: string | undefined =
    `https://graph.facebook.com/v25.0/${wabaId}/message_templates` +
    `?fields=${encodeURIComponent(fields)}&limit=100`;

  while (next) {
    const response = await fetch(next, {
      headers: { Authorization: `Bearer ${accessToken}` }
    });

    const body = await response.json();
    if (!response.ok) {
      const code = body?.error?.code;
      // 4 e 80007: reagende com backoff; não faça retry imediato em loop.
      throw new Error(`Meta template sync failed: ${code ?? response.status}`);
    }

    const page = body as MetaTemplatePage;
    for (const template of page.data ?? []) {
      await upsertTemplate({
        wabaId,
        metaTemplateId: template.id,
        name: template.name,
        language: template.language,
        status: template.status,
        category: template.category,
        components: template.components ?? [],
        qualityScore: template.quality_score ?? null,
        rejectedReason: template.rejected_reason ?? null,
        metaLastUpdatedAt: template.last_updated_time ?? null,
        lastSyncedAt: new Date().toISOString()
      });
    }

    next = page.paging?.next;
  }
}

Atualizações de status já administradas pela HookCloud

O campo técnico message_template_status_update já está habilitado no App da HookCloud. Isso significa que o assinante não precisa configurar o campo, informar App Secret ou manter uma assinatura de App por conta própria.

Para manter sua própria base atualizada, trate o GET de templates como reconciliação da fonte de verdade. Uma estratégia segura é sincronizar quando o usuário solicitar, após uma alteração conhecida ou em uma agenda moderada. O objetivo é evitar polling agressivo sem perder a capacidade de confirmar o estado atual.

GET excessivo, rate limit e erros de requisição

Chamadas à Graph API consomem limites do app e do caso de uso da WABA. Paginação, retries e chamadas duplicadas também aumentam o volume. Quando o limite é atingido, você pode receber códigos como 4 ou 80007, além de falhas temporárias.

Backoff sugerido

Para erros transitórios, use uma fila com atrasos crescentes, por exemplo 30 segundos, 2 minutos, 5 minutos e 15 minutos, com pequena variação aleatória. Pare o retry quando o erro exigir correção humana, como token inválido, permissão ausente, template desabilitado ou problema de pagamento.

Antes de enviar um template

1. Confirme que o template local está APPROVED e não está pausado ou desabilitado.
2. Use exatamente o nome e o idioma cadastrados na Meta.
3. Monte os componentes na mesma ordem e tipo do modelo aprovado.
4. Preencha todas as variáveis obrigatórias e não envie valores vazios.
5. Em header de mídia, use tipo e formato compatíveis.
6. Confirme opt-in e finalidade correta da categoria.
7. Guarde o wamid retornado e acompanhe os status de entrega no webhook configurado para a operação.

Uma resposta HTTP de sucesso significa que a Meta aceitou a solicitação; a entrega final ainda pode falhar depois. A configuração do App da HookCloud já está pronta. O assinante precisa apenas tratar os eventos que chegam ao webhook da própria operação e manter o catálogo local coerente.

Erros ao listar ou sincronizar templates

Erros comuns de envio ou entrega de templates

A Meta pode devolver o erro imediatamente na API ou depois, no status failed do webhook. Sempre registre código, detalhes, horário, WABA ID, Phone Number ID, nome/idioma do template e wamid.

Erros específicos do template

Passo a passo para o erro 131042: pagamento/elegibilidade

Passo a passo para o erro 131049

A mensagem “This message was not delivered to maintain healthy ecosystem engagement” geralmente não é um defeito de token, webhook ou template inexistente. É uma decisão de entrega da Meta, especialmente em mensagens de marketing.

1. Não repita a mesma mensagem em sequência.
2. Registre o contato em uma lista temporária de supressão.
3. Aguarde antes de uma nova tentativa; a Meta não publica um único prazo garantido para todos os casos.
4. Reduza frequência e melhore segmentação/engajamento.
5. Confirme opt-in e pedidos de parada.
6. Use Utility apenas quando a finalidade for realmente transacional; não troque a categoria para burlar a decisão.
7. Acompanhe qualidade do template e do número no WhatsApp Manager.

Consulte os limites de marketing por usuário na documentação da Meta.

O que salvar para diagnosticar sem expor segredos

• código, título e error_data.details;
• fbtrace_id e horário UTC;
• WABA ID, Phone Number ID, template ID, nome e idioma;
• wamid quando a API aceitou o envio;
• status local do template e data da última sincronização;
• tentativa, backoff aplicado e resposta HTTP;
• nunca o token completo; e nunca solicite o App Secret da HookCloud.