Genuka WA docs

Errore WhatsApp 131047: Re-engagement message — soluzione

L'errore WhatsApp 131047 (Re-engagement message) significa che la finestra di 24 ore è chiusa. Perché Meta rifiuta il messaggio libero e come passare a un modello.

L'errore WhatsApp 131047 significa che sono passate più di 24 ore dall'ultimo messaggio che il destinatario ti ha inviato: la finestra di assistenza clienti è chiusa, e solo un modello approvato può ancora raggiungerlo. La soluzione è semplice: rinvia il contenuto come modello, poi torna ai messaggi liberi appena il cliente risponde.

Cosa significa l'errore 131047?

"More than 24 hours have passed since the recipient last replied to the sender number." — Meta, Cloud API error codes

La soluzione suggerita da Meta sta in una riga: "Send the recipient a template message instead." Nel campo message della risposta, il codice è seguito dal suo titolo, "Re-engagement message" (elenco di 360dialog); Meta avverte che questi titoli saranno deprecati, quindi non basare il tuo codice su di essi.

La regola dietro il codice è la finestra di assistenza clienti. Quando un utente ti scrive o ti chiama, parte un timer di 24 ore; ogni suo nuovo messaggio o chiamata lo riporta a 24 ore. Finché è attivo puoi inviare qualsiasi messaggio libero: testo, immagine, pulsanti, lista. Una volta scaduto, passano solo i modelli approvati (Meta, Send messages).

Quando si verifica l'errore 131047?

  • Un messaggio libero inviato troppo tardi: la risposta dell'assistenza parte la mattina dopo, mentre il cliente aveva scritto alle 8 del giorno prima.
  • Un primo messaggio libero a qualcuno che non ti ha mai scritto: non esiste alcuna finestra.
  • Un Flow inviato come messaggio interattivo fuori dalla finestra: stessa regola, vedi i Flow nella libreria.
  • Il blocco di un utente: Meta ti permette di bloccare solo un numero che ti ha scritto nelle ultime 24 ore (Meta, Block users). POST /api/v1/blocked-users riporta allora il fallimento numero per numero, con il codice 131047 e il messaggio "Failed to block due to re-engagement check failed", che abbiamo registrato su un numero reale il 13 agosto 2026.

Perché l'API risponde 200 quando il messaggio non arriva mai?

È la trappola principale di questo codice. Il 13 agosto 2026, su un numero reale, abbiamo inviato tre testi liberi fuori dalla finestra: Meta ha risposto HTTP 200 con un wamid valido per ciascuno, e nessuno è stato consegnato. Nessun 131047 alla chiamata. Un modello inviato allo stesso destinatario subito dopo è arrivato all'istante.

A seconda del caso, l'errore torna alla chiamata, più tardi sul webhook di stato, oppure per niente. Per questo Genuka WA controlla la finestra dal suo lato prima di ogni messaggio libero e lo segnala nella risposta, senza bloccare l'invio:

200 — POST /api/v1/messages outside the window
{
  "data": {
    "messageId": "wamid.HBgLMjM3...",
    "warning": {
      "code": "outside_service_window",
      "message": "This contact last messaged you at 2026-10-06T08:12:44.000Z, more than 24 hours ago, so the service window is closed. Meta will most likely drop this message; send an approved template instead."
    }
  }
}

Dove lo vedi in Genuka WA?

CanaleCosa ottieni
Risposta 200 di POST /api/v1/messagesdata.warning.code: outside_service_window (ultimo messaggio in entrata più di 24 h fa) oppure unverified_service_window (nessun messaggio in entrata registrato per questo contatto)
Risposta 400 di POST /api/v1/messages"error": "send_needs_template", meta.code: 131047, quando Meta rifiuta già alla chiamata
Webhook message_statusdata.status: "failed" e data.errors[0].code: 131047
Dashboard, sezione InboxLa bolla in errore; "Scopri perché" mostra il codice e i dettagli di Meta

Il warning non è mai un rifiuto: il nostro registro della finestra viene dal flusso dei webhook, e un disservizio dal nostro lato non deve bloccare un invio che Meta avrebbe consegnato. La decisione è tua.

Come risolvo l'errore 131047?

Non rinviare il messaggio libero. Fallirà esattamente allo stesso modo. Genuka WA classifica 131047 come needs_template e non lo riprova mai, né in un invio singolo né in una campagna.

Scegli un modello approvato del tipo giusto: UTILITY per informazioni su un ordine o un account, MARKETING per una promozione. L'elenco si trova su GET /api/v1/templates?status=approved per i modelli creati tramite Genuka WA; quelli creati in WhatsApp Manager non ci sono, ma si inviano allo stesso modo.

Invialo con il campo template sullo stesso endpoint, passando sempre language.

Torna ai messaggi liberi quando il cliente risponde. La sua risposta apre una nuova finestra di 24 ore.

curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": { "name": "order_update", "language": "en", "body": ["Awa", "ORD-1042"] }
  }'
# { "data": { "messageId": "wamid.HBg..." } }

Se il messaggio libero è già partito e un webhook message_status torna failed con il codice 131047, vale la stessa regola: rinvia il contenuto come modello, una sola volta.

Come prevengo l'errore 131047?

  • Tieni un tuo orologio della finestra. Ogni messaggio in entrata arriva al tuo webhook con il mittente e un timestamp: salva il più recente per ogni contatto e scegli tra modello e messaggio libero prima di inviare.
  • Leggi data.warning. Quando è presente, considera che il messaggio libero probabilmente non sarà consegnato, e tieni d'occhio il suo stato.
  • Usa un modello per tutto ciò che avvii tu: conferma d'ordine, promemoria di appuntamento, codice di accesso. La guida alle notifiche d'ordine si basa su questo principio.
  • Tieni pronto un modello di riattivazione nella categoria UTILITY, breve, che inviti il cliente a rispondere così che la conversazione si riapra.

Codici di errore correlati

  • 132001: il modello che hai scelto per riattivare il contatto non esiste in quella lingua o non è approvato.
  • 132000: il modello viene trovato, ma il numero di variabili non corrisponde.
  • 131050: il destinatario ha interrotto i messaggi di marketing; nemmeno un modello MARKETING passerà.
  • 131026: il destinatario non può ricevere alcun messaggio, modelli compresi.

FAQ

Le 24 ore partono dal mio ultimo messaggio o dal suo?

Dal suo. La finestra parte dall'ultimo messaggio o chiamata del cliente; i messaggi che invii tu non la prolungano.

Un modello riapre la finestra di 24 ore?

No, è la risposta del cliente a farlo. Meta lo dice chiaramente per i modelli di marketing: se l'utente risponde, parte una finestra di assistenza clienti di 24 ore (Meta, Per-user marketing limits).

Un messaggio libero inviato dentro la finestra viene fatturato?

Meta lo marca free_customer_service nel webhook di stato: un messaggio non basato su modello inviato dentro una finestra di assistenza clienti è gratuito, come lo è un modello UTILITY inviato dentro la finestra (Meta, status webhook). I modelli sono fatturati da Meta direttamente al WhatsApp Business Account del cliente; Genuka WA non aggiunge alcun ricarico.

Posso bloccare un numero che non mi ha mai scritto?

No. Il blocco richiede un messaggio in entrata nelle ultime 24 ore, altrimenti Meta risponde 131047 per quel numero. POST /api/v1/blocked-users restituisce 207 quando alcuni numeri sono andati a buon fine, 422 quando nessuno ci è riuscito.

Fonti

In questa pagina