← Todos os artigos

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çãoJanela
Cliente manda mensagem às 10h de segundaAberta até 10h de terça
Cliente manda outra mensagem às 15h de segundaRenovada até 15h de terça
Sua empresa responde várias vezesNão muda o prazo
Cliente não responde maisFecha 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:

  1. Guarde a data e hora da última mensagem recebida de cada contato (ela chega no webhook de mensagens).
  2. Antes de enviar, compare com a hora atual.
  3. 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.

Onde vejo a lista completa de tipos de mensagem e erros?

Na documentação da Datafy API.