Erro 131047 WhatsApp API: Mensagem Fora da Janela de 24 Horas

O que é o Erro 131047?

O erro 131047 é um dos erros mais comuns na WhatsApp Business API. Ele ocorre quando você tenta enviar uma mensagem de texto livre (free-form message) para um usuário após 24 horas desde a última mensagem que ele enviou.

A mensagem de erro geralmente aparece assim:

{
  "error": {
    "message": "Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "fbtrace_id": "..."
  }
}

Por que isso acontece?

A Meta implementou uma política de janela de conversa de 24 horas para proteger os usuários de spam. Funciona assim:

1. Quando o usuário envia uma mensagem, uma janela de 24 horas é aberta
2. Durante essa janela, você pode enviar mensagens livres (texto, imagem, vídeo, etc.)
3. A janela se renova cada vez que o usuário envia uma nova mensagem
4. Após 24 horas sem resposta do usuário, a janela fecha e você só pode usar templates

Como Resolver

Solução 1: Use Message Templates

A única forma de iniciar uma conversa ou reengajar um usuário fora da janela de 24 horas é usando um Message Template aprovado pela Meta.

// Exemplo de envio de template com Node.js
const response = await fetch(
  `https://graph.facebook.com/v18.0/${phoneNumberId}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: recipientPhone,
      type: 'template',
      template: {
        name: 'hello_world', // nome do seu template aprovado
        language: {
          code: 'pt_BR'
        }
      }
    })
  }
);

Solução 2: Verifique o Status da Conversa

Antes de enviar mensagens, verifique se a janela ainda está aberta:

// Armazene o timestamp da última mensagem do usuário
const lastUserMessage = await getLastUserMessageTime(userId);
const now = Date.now();
const hoursSinceLastMessage = (now - lastUserMessage) / (1000 * 60 * 60);

if (hoursSinceLastMessage > 24) {
  // Use template
  await sendTemplateMessage(userId);
} else {
  // Pode usar mensagem livre
  await sendFreeFormMessage(userId);
}

Solução 3: Implemente um Sistema de Fallback

async function sendMessage(userId, message) {
  try {
    // Tenta enviar mensagem livre
    await sendFreeFormMessage(userId, message);
  } catch (error) {
    if (error.code === 131047) {
      // Fallback para template
      console.log('Janela expirada, usando template...');
      await sendTemplateMessage(userId);
    } else {
      throw error;
    }
  }
}

Tipos de Conversa e Custos

A partir de 2025, a Meta categoriza as conversas em:

| Tipo | Descrição | Custo | |------|-----------|-------| | Service | Iniciada pelo usuário | Mais barato | | Utility | Templates transacionais | Médio | | Marketing | Templates promocionais | Mais caro | | Authentication | Códigos de verificação | Médio |

Boas Práticas

1. Responda rapidamente: Tente responder dentro da janela de 24h
2. Crie templates úteis: Tenha templates aprovados para reengajamento
3. Monitore as janelas: Implemente tracking de quando cada conversa expira
4. Seja relevante: Só reengaje usuários que realmente precisam da informação

Conclusão

O erro 131047 não é um bug, é uma feature de proteção ao usuário. A solução é entender o sistema de janelas da WhatsApp API e usar Message Templates aprovados quando necessário.

Se você precisa de ajuda implementando integrações com a WhatsApp Business API, entre em contato para consultoria especializada.