A janela de 24 horas do WhatsApp: o que abre, o que fecha e onde a conta erra

A regra, sem eufemismo

Dentro da janela de atendimento você envia o que quiser: texto, mídia, mensagem interativa, flow. Fora dela, só template aprovado. Não existe meio-termo, e não existe categoria de mensagem que escape — a Meta recusa com o erro 131047 e a mensagem não sai.

A janela abre quando o cliente te manda uma mensagem e dura 24 horas a partir dela. Cada nova mensagem do cliente reabre o relógio. Simples de enunciar, e é justamente por parecer simples que quase toda implementação erra o mesmo detalhe.

O relógio certo é o da Meta, não o seu

O webhook da Meta traz um campo timestamp com o momento em que a mensagem foi recebida por ela, em segundos Unix. É esse o instante que abre a janela. O momento em que o seu servidor processou o webhook não é.

Parece a mesma coisa e quase sempre é — até o dia em que não é. Webhook tem reentrega. Se a Meta reentregar um evento com atraso, ou se a sua fila acumular durante um incidente, o seu cálculo passa a conceder uma janela mais generosa do que a real. O sistema fica convencido de que pode mandar texto livre, a Meta discorda, e o 131047 aparece numa conversa que a sua própria tela desenha como aberta.

O sintoma é cruel porque a tela e a Meta contam histórias diferentes sobre o mesmo dado, e a tela parece confiável. Nós ancoramos a janela no timestamp do payload depois de uma auto-resposta de boas-vindas falhar exatamente assim, com a conversa aberta na interface.

A mensagem que chega e não abre nada

Nem toda mensagem recebida abre a janela. Quando o cliente envia algo que a Cloud API não sabe representar — certos tipos de anexo, mensagens de sistema, conteúdo que a Meta classifica como unsupported — o evento chega ao seu webhook com o tipo unsupported, normalmente acompanhado do erro 131051 no array de erros.

Esse evento não abre janela nenhuma do lado da Meta. Se o seu roteador de tipos joga unsupported no mesmo balde de interactive (um erro fácil de cometer, porque estruturalmente eles se parecem), você acabou de registrar uma janela que não existe — e vai disparar auto-resposta e agente de IA contra uma conversa que só aceita template.

A regra que ficou no nosso código: mensagem com tipo unsupported, ou com qualquer coisa dentro de errors[], não abre janela, não dispara auto-resposta e não acorda a IA. Ela é registrada no histórico para o atendente ver que algo chegou, e para por aí.

Flow e interativa não são exceção

Existe uma crença comum de que mensagem interativa e flow escapam da janela por serem “estruturadas”. Não escapam. Um flow enviado fora da janela é recusado igual a um texto solto.

Para reengajar alguém fora da janela com um flow, o flow precisa estar embrulhado num template de flow aprovado — é outro objeto, com outro ciclo de aprovação. Não é uma flag no envio.

Vale checar isso no seu guard antes de chamar a Meta. Bloquear localmente com um erro claro custa milissegundos; descobrir pelo 131047 custa uma ida à API, uma entrada de erro no histórico do cliente e, dependendo do seu fluxo de retry, uma escada de tentativas que nunca vai passar.