Errore WhatsApp 131026: Message undeliverable — soluzione
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):
"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). 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 sempretoin 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 |
{
"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?
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.
Controlla il numero così come l'hai salvato: prefisso internazionale, cifre in più o in meno, un numero digitato in un campo "telefono fisso".
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.
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.
// 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");
}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_statusinvece della risposta all'invio: un200significa "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 lo prevede.
Codici di errore correlati
- 131050: il destinatario riceve WhatsApp, ma ha interrotto i tuoi messaggi di marketing.
- 131049: un messaggio di marketing trattenuto da Meta per questo destinatario, da riprovare più tardi.
- 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). 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
Errore WhatsApp 100: Invalid parameter — causa e soluzione
Errore 100 della WhatsApp Cloud API (Invalid parameter): un parametro sconosciuto, scritto male o troppo lungo. Come leggere details e correggere la richiesta.
Errore WhatsApp 131042: problema con il metodo di pagamento — soluzione
Errore WhatsApp 131042: Meta rifiuta l'invio perché il WhatsApp Business Account non ha un metodo di pagamento valido. Dove aggiungere la carta e come verificarla.