O que é a janela de 24 horas do WhatsApp e quando usar template
Entenda a janela de atendimento de 24 horas da API oficial do WhatsApp, o que dá para enviar dentro e fora dela e como evitar o erro 131047.
A janela de 24 horas é o período em que sua empresa pode mandar mensagens livres (texto, imagem, áudio, documento) para um contato pela API oficial do WhatsApp. Ela abre quando o cliente envia uma mensagem para o seu número e fica aberta por 24 horas a partir da última mensagem dele. Fora da janela, só é possível iniciar a conversa com um template aprovado pela Meta.
Essa regra é da Meta e vale para qualquer provedor da API oficial, incluindo a Datafy API.
Quando a janela de 24 horas abre?
A janela abre (ou é renovada) toda vez que o contato envia uma mensagem para o seu número. O prazo conta a partir da última mensagem recebida do cliente, não da primeira.
| Situação | Janela |
|---|---|
| Cliente manda mensagem às 10h de segunda | Aberta até 10h de terça |
| Cliente manda outra mensagem às 15h de segunda | Renovada até 15h de terça |
| Sua empresa responde várias vezes | Não muda o prazo |
| Cliente não responde mais | Fecha 24h após a última mensagem dele |
Mensagens enviadas pela empresa não renovam a janela. Só a resposta do cliente renova.
O que posso enviar dentro da janela?
Com a janela aberta, você pode enviar qualquer tipo de mensagem suportado pela API, sem precisar de aprovação prévia:
- texto livre;
- imagem, vídeo, áudio e documento;
- mensagens interativas (botões e listas);
- localização e contatos;
- templates (também são permitidos dentro da janela).
Exemplo de texto livre:
curl -X POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "text",
"text": { "body": "Seu pedido foi separado e sai para entrega hoje." }
}'
O que acontece se eu mandar mensagem livre fora da janela?
A mensagem não é entregue. A API aceita a requisição, mas o webhook de status devolve uma falha com o código de erro 131047 (Re-engagement message), indicando que já se passaram mais de 24 horas desde a última resposta do cliente.
Se você vê esse erro com frequência, o seu sistema está tentando falar com contatos cuja janela já fechou. A solução é trocar a mensagem livre por um template.
Como falar com o cliente depois de 24 horas?
Envie um template de mensagem: um modelo de texto cadastrado e aprovado pela Meta antes do uso. Templates podem ter variáveis (nome, número do pedido, data) e botões.
curl -X POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "template",
"template": {
"name": "atualizacao_pedido",
"language": { "code": "pt_BR" }
}
}'
Os campos principais:
name: o nome exato do template aprovado.language.code: o idioma em que o template foi aprovado (por exemplo,pt_BR).
Quando o cliente responde ao template, uma nova janela de 24 horas se abre e você volta a poder enviar mensagens livres.
Como saber se a janela de um contato está aberta?
A API não tem um campo que diga "janela aberta" ou "fechada". O controle fica do seu lado:
- Guarde a data e hora da última mensagem recebida de cada contato (ela chega no webhook de mensagens).
- Antes de enviar, compare com a hora atual.
- Se passou de 24 horas, use um template. Se não passou, pode mandar mensagem livre.
Perguntas frequentes
Enviar um template abre a janela?
Não. A janela só abre quando o cliente envia uma mensagem. O template serve justamente para iniciar o contato quando ela está fechada.
Preciso de template para responder um cliente que acabou de me escrever?
Não. Se ele escreveu há menos de 24 horas, a janela está aberta e você pode responder com mensagem livre.