# Errore WhatsApp 131026: Message undeliverable — soluzione

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

> Errore WhatsApp 131026 (Message Undeliverable): numero non presente su WhatsApp, condizioni non accettate o app troppo vecchia. Come diagnosticarlo e cosa fare dopo.

L'errore WhatsApp 131026 significa che Meta non è riuscita a consegnare il messaggio al destinatario: il numero
non è su WhatsApp, la persona non ha accettato gli ultimi termini di servizio, oppure la sua app è troppo
vecchia. Non riprovare su WhatsApp. Controlla il numero che hai salvato, poi raggiungi la persona tramite un altro
canale, come SMS o email.

## Cosa significa l'errore 131026?

Meta lo descrive così
([Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)):

> "Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp
> phone number. Recipient has not accepted the new Terms of Service and Privacy Policy. Recipient
> using an old WhatsApp version."

Tre cause possibili, tutte dal lato del destinatario. Per la terza, Meta elenca le versioni minime
dell'app:

| App                               | Versione minima |
| --------------------------------- | --------------- |
| Android                           | 2.21.15.15      |
| SMBA (WhatsApp Business, Android) | 2.21.15.15      |
| iOS                               | 2.21.170.4      |
| SMBI (WhatsApp Business, iOS)     | 2.21.170.4      |
| KaiOS                             | 2.2130.10       |
| Web                               | 2.2132.6        |

Il titolo che accompagna il codice nel campo `message` è "Message Undeliverable"
([elenco di 360dialog](https://docs.360dialog.com/docs/support/api-error-message-list)). Descrive il
sintomo, non la causa: sono il codice e `error_data.details` a dirti il perché.

## Quando si verifica l'errore 131026?

* **Il numero non ha un account WhatsApp**: un fisso, il numero di un centralino, un errore di battitura in un modulo.
* **Il numero è formattato male**: senza `+` e prefisso internazionale, un numero locale può essere interpretato
  come appartenente a un altro paese e finire su qualcuno senza WhatsApp. Scrivi sempre `to` in
  formato internazionale, per esempio `+237690000001`.
* **L'app del destinatario non è aggiornata**, oppure non ha accettato i nuovi termini di servizio.

### Dove lo vedi in Genuka WA?

Il caso più comune: Meta accetta l'invio, poi segnala il fallimento sul webhook di stato.

| Canale                                                                     | Cosa ottieni                                                                                          |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Webhook `message_status`                                                   | `data.status: "failed"`, `data.errors[0].code: 131026`                                                |
| Risposta di `POST /api/v1/messages`, quando Meta rifiuta già alla chiamata | `400`, `"error": "send_recipient_permanent"`, `meta.code: 131026`                                     |
| Campagna                                                                   | Il destinatario diventa `failed`, con il messaggio di Meta in `errorMessage`; non viene mai riprovato |
| Dashboard, sezione Inbox                                                   | La bolla in errore; "Scopri perché" mostra il codice e i dettagli di Meta                             |

```json title="message_status webhook received by your endpoint (excerpt)"
{
  "id": "dlv_2f8c1a...",
  "type": "message_status",
  "field": "messages",
  "connection_id": "cn77...",
  "data": {
    "id": "wamid.HBgLMjM3...",
    "status": "failed",
    "timestamp": "1791451867",
    "recipient_id": "237690000001",
    "errors": [
      {
        "code": 131026,
        "title": "…",
        "message": "…",
        "error_data": { "details": "…" },
        "href": "/documentation/business-messaging/whatsapp/support/error-codes"
      }
    ]
  }
}
```

`data` è l'oggetto di stato di Meta, inoltrato senza modifiche: `error_data.details` varia a seconda
del caso e può indicare la causa.

## Come risolvo l'errore 131026?

1. **Non riprovare su WhatsApp.** Lo stesso invio fallirà allo stesso modo. Genuka WA classifica 131026 come
   `recipient_permanent` e non lo riprova mai, né in una campagna né in un invio singolo.
2. **Controlla il numero così come l'hai salvato**: prefisso internazionale, cifre in più o in meno, un numero digitato
   in un campo "telefono fisso".
3. **Raggiungi la persona tramite un altro canale**, SMS o email, come consiglia Meta, e chiedile di
   verificare tre cose: che riesca lei stessa a scrivere al tuo numero WhatsApp Business, che abbia
   accettato gli ultimi termini (Meta cita le schermate **Settings > Help** e **Settings > Application
   information**, che mostrano l'avviso se serve) e che la sua app sia aggiornata.
4. **Segna il contatto come non raggiungibile su WhatsApp** nel tuo database, e riattivalo solo quando ti
   scrive: un messaggio in entrata dimostra che può ricevere.

**Node.js**

```ts
// app/api/webhooks/whatsapp/route.ts
import { verifySignature } from "@genuka/whatsapp/webhooks";

export async function POST(request: Request) {
  const raw = await request.text();
  const signature = request.headers.get("x-genuka-signature");
  if (!(await verifySignature(process.env.WEBHOOK_SECRET!, raw, signature))) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(raw);
  if (event.type === "message_status" && event.data.status === "failed") {
    const codes: number[] = (event.data.errors ?? []).map((e: { code: number }) => e.code);
    if (codes.includes(131026)) {
      // Yours to write: the contact moves to SMS/email until their next inbound message.
      void markWhatsAppUnreachable(event.data.recipient_id);
    }
  }
  return new Response("ok");
}
```

**Python**

```python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

app = Flask(__name__)


def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = int(parts.get("t", "0"))
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))


@app.post("/webhooks/whatsapp")
def whatsapp_webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("X-Genuka-Signature", ""), os.environ["WEBHOOK_SECRET"]):
        return "invalid signature", 401

    event = json.loads(raw)
    if event["type"] == "message_status" and event["data"]["status"] == "failed":
        codes = [error["code"] for error in event["data"].get("errors", [])]
        if 131026 in codes:
            mark_whatsapp_unreachable(event["data"]["recipient_id"])  # your function
    return "ok"
```

## Come prevengo l'errore 131026?

* **Valida i numeri in fase di inserimento**, in formato internazionale con prefisso.
* **Fatti contattare prima su WhatsApp** quando puoi, con un link "Scrivici su
  WhatsApp": un numero che ti ha già scritto è un numero che riceve.
* **Ascolta il webhook `message_status`** invece della risposta all'invio: un `200` significa
  "accettato da Meta", non "consegnato".
* **Tieni un canale di riserva** per i messaggi critici come i codici di accesso. La
  [guida WhatsApp OTP in Node.js](https://wa.genuka.com/it/docs/guides/whatsapp-otp-nodejs) lo prevede.

## Codici di errore correlati

* [131050](https://wa.genuka.com/it/docs/errors/131050): il destinatario riceve WhatsApp, ma ha interrotto i tuoi
  messaggi di marketing.
* [131049](https://wa.genuka.com/it/docs/errors/131049): un messaggio di marketing trattenuto da Meta per questo destinatario,
  da riprovare più tardi.
* [131047](https://wa.genuka.com/it/docs/errors/131047): la finestra di 24 ore è chiusa; un modello passerà.

## FAQ

### Devo riprovare un invio fallito con 131026?

Non su WhatsApp. Finché la situazione del destinatario non cambia (WhatsApp installato, app aggiornata, termini
accettati), lo stesso invio fallirà.

### Perché la risposta all'invio era 200 se il messaggio è fallito?

Perché Meta ha accettato la richiesta prima di tentare la consegna. Meta precisa che i suoi errori
tornano nella risposta, via webhook o in entrambi, e consiglia di controllarli tutti e due. Un 131026 arriva
molto spesso sul webhook di stato.

### Come trovo i destinatari 131026 di una campagna?

`GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000` elenca i destinatari falliti con il
messaggio di Meta, 200 di default e 1.000 al massimo, senza paginazione. Il codice numerico arriva sul
webhook `message_status`: salvalo lì se vuoi filtrare per causa, ed è l'unico elenco
completo per una campagna grande.

### Un messaggio fallito con 131026 viene fatturato?

Non da Meta, che addebita un modello di messaggio solo quando viene consegnato
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Lato Genuka WA, invece, un invio accettato da Meta conta sulla quota del tuo abbonamento anche
se la consegna fallisce in seguito: togli i numeri non raggiungibili dai tuoi prossimi invii.

## Fonti

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Status webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [360dialog — API error message list](https://docs.360dialog.com/docs/support/api-error-message-list)
