Genuka WA docs

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:

AppVersione minima
Android2.21.15.15
SMBA (WhatsApp Business, Android)2.21.15.15
iOS2.21.170.4
SMBI (WhatsApp Business, iOS)2.21.170.4
KaiOS2.2130.10
Web2.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 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.

CanaleCosa ottieni
Webhook message_statusdata.status: "failed", data.errors[0].code: 131026
Risposta di POST /api/v1/messages, quando Meta rifiuta già alla chiamata400, "error": "send_recipient_permanent", meta.code: 131026
CampagnaIl destinatario diventa failed, con il messaggio di Meta in errorMessage; non viene mai riprovato
Dashboard, sezione InboxLa bolla in errore; "Scopri perché" mostra il codice e i dettagli di Meta
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?

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_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 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

In questa pagina