# Errore WhatsApp 131047: Re-engagement message — soluzione

URL: https://wa.genuka.com/it/docs/errors/131047
Language: Italian

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

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](https://docs.360dialog.com/docs/support/api-error-message-list)); 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)).

## 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](https://wa.genuka.com/sdk/flows).
* **Il blocco di un utente**: Meta ti permette di bloccare solo un numero che ti ha scritto nelle ultime 24 ore
  ([Meta, Block users](https://developers.facebook.com/documentation/business-messaging/whatsapp/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:

```json title="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?

| Canale                                    | Cosa ottieni                                                                                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Risposta `200` di `POST /api/v1/messages` | `data.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_status`                  | `data.status: "failed"` e `data.errors[0].code: 131047`                                                                                                                                    |
| Dashboard, sezione Inbox                  | La 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?

1. **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.
2. **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.
3. **Invialo con il campo `template`** sullo stesso endpoint, passando sempre `language`.
4. **Torna ai messaggi liberi quando il cliente risponde.** La sua risposta apre una nuova finestra di 24 ore.

**curl**

```bash
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..." } }
```

**Node.js**

```ts
const API = "https://wa.genuka.com/api/v1";
const WINDOW_MS = 24 * 60 * 60 * 1000;

async function post(path: string, body: unknown) {
  const response = await fetch(`${API}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const json = await response.json();
  if (!response.ok) throw Object.assign(new Error(json.message ?? json.error), json);
  return json.data as { messageId: string; warning?: { code: string; message: string } };
}

// lastInboundAt: when this contact last wrote to you, kept up to date by your webhooks.
export async function notify(to: string, text: string, lastInboundAt: Date | null) {
  const windowOpen = lastInboundAt !== null && Date.now() - lastInboundAt.getTime() < WINDOW_MS;
  const template = {
    connectionId: "con_1",
    to,
    template: { name: "order_update", language: "en", body: ["Awa", "ORD-1042"] },
  };
  if (!windowOpen) return post("/messages", template);

  try {
    return await post("/messages", { connectionId: "con_1", to, text });
  } catch (error) {
    if ((error as { error?: string }).error === "send_needs_template") return post("/messages", template);
    throw error;
  }
}
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://wa.genuka.com/api/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
        "User-Agent": "acme-crm/1.0 (+https://example.com)",
    },
    json={
        "connectionId": "con_1",
        "to": "+237690000001",
        "template": {"name": "order_update", "language": "en", "body": ["Awa", "ORD-1042"]},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"]["messageId"])
```

**PHP**

```php
<?php
$ch = curl_init("https://wa.genuka.com/api/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERAGENT => "acme-crm/1.0 (+https://example.com)",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("GENUKA_WA_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "connectionId" => "con_1",
        "to" => "+237690000001",
        "template" => ["name" => "order_update", "language" => "en", "body" => ["Awa", "ORD-1042"]],
    ]),
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $json["data"]["messageId"] ?? $json["error"];
```

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](https://wa.genuka.com/it/docs/guides/order-notifications) 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](https://wa.genuka.com/it/docs/errors/132001): il modello che hai scelto per riattivare il contatto non esiste in quella
  lingua o non è approvato.
* [132000](https://wa.genuka.com/it/docs/errors/132000): il modello viene trovato, ma il numero di variabili non
  corrisponde.
* [131050](https://wa.genuka.com/it/docs/errors/131050): il destinatario ha interrotto i messaggi di marketing; nemmeno un modello `MARKETING`
  passerà.
* [131026](https://wa.genuka.com/it/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).
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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Send messages, customer service windows](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)
* [Meta — Status webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Per-user marketing template message limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)
* [Meta — Block users](https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users)
* [360dialog — API error message list](https://docs.360dialog.com/docs/support/api-error-message-list)
