# Error 131026 de WhatsApp: mensaje no entregable — solución

URL: https://wa.genuka.com/es/docs/errors/131026
Language: Spanish

> Error 131026 de WhatsApp (Message Undeliverable): número sin WhatsApp, términos no aceptados o aplicación demasiado antigua. Cómo diagnosticarlo y qué hacer después.

El error 131026 de WhatsApp significa que Meta no pudo entregar el mensaje al destinatario: el
número no está en WhatsApp, la persona no ha aceptado los términos del servicio más recientes o su
aplicación es demasiado antigua. No reintentes por WhatsApp. Verifica el número que guardaste y
luego contacta a la persona por otro canal, como SMS o correo electrónico.

## ¿Qué significa el error 131026?

Meta lo describe así
([códigos de error de la Cloud API](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."

(No se pudo entregar el mensaje. Las razones pueden incluir: el número de teléfono del destinatario
no es un número de WhatsApp; el destinatario no ha aceptado los nuevos Términos del servicio y la
Política de privacidad; el destinatario usa una versión antigua de WhatsApp).

Tres causas posibles, todas del lado del destinatario. Para la tercera, Meta indica las versiones
mínimas de la aplicación:

| Aplicación                        | Versión mínima |
| --------------------------------- | -------------- |
| 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       |

El título que acompaña al código en el campo `message` es "Message Undeliverable"
([lista de 360dialog](https://docs.360dialog.com/docs/support/api-error-message-list)). Nombra el
síntoma, no la causa: el código y `error_data.details` son los que te dicen por qué.

## ¿Cuándo aparece el error 131026?

* **El número no tiene cuenta de WhatsApp**: un teléfono fijo, un conmutador, un error de tipeo en
  un formulario.
* **El número tiene un formato incorrecto**: sin `+` ni código de país, un número local puede
  interpretarse como de otro país y llegar a alguien sin WhatsApp. Escribe siempre `to` en formato
  internacional, por ejemplo `+237690000001`.
* **La aplicación del destinatario está desactualizada**, o no ha aceptado los nuevos términos del
  servicio.

### ¿Dónde lo ves en Genuka WA?

El caso más frecuente: Meta acepta el envío y luego informa el fallo en el webhook de estado.

| Canal                                                                        | Qué recibes                                                                                   |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Webhook `message_status`                                                     | `data.status: "failed"`, `data.errors[0].code: 131026`                                        |
| Respuesta de `POST /api/v1/messages`, cuando Meta rechaza durante la llamada | `400`, `"error": "send_recipient_permanent"`, `meta.code: 131026`                             |
| Campaña                                                                      | El destinatario pasa a `failed`, con el mensaje de Meta en `errorMessage`; nunca se reintenta |
| Panel, sección Bandeja de entrada                                            | La burbuja fallida; "Ver por qué" muestra el código y los detalles de Meta                    |

```json title="Webhook message_status recibido por tu endpoint (extracto)"
{
  "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` es el objeto de estado de Meta, transmitido sin cambios: `error_data.details` varía según
el caso y puede nombrar la causa.

## ¿Cómo corrijo el error 131026?

1. **No reintentes por WhatsApp.** El mismo envío fallará de la misma manera. Genuka WA clasifica el
   131026 como `recipient_permanent` y nunca lo reintenta, ni en una campaña ni en un envío
   individual.
2. **Verifica el número tal como lo guardaste**: código de país, dígitos de más o de menos, un número
   escrito en un campo de "teléfono fijo".
3. **Contacta a la persona por otro canal**, SMS o correo electrónico, como recomienda Meta, y pídele
   que verifique tres cosas: que puede escribir ella misma a tu número de WhatsApp Business, que
   aceptó los términos más recientes (Meta remite a **Ajustes > Ayuda** y **Ajustes > Información de
   la aplicación**, que muestran el aviso cuando hace falta) y que su aplicación está actualizada.
4. **Marca el contacto como no localizable por WhatsApp** en tu base de datos, y solo vuelve a
   activarlo cuando te escriba: un mensaje entrante demuestra que puede recibir.

**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)) {
      // Función que escribes tú: el contacto pasa a SMS/correo hasta su próximo mensaje entrante.
      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"])  # tu función
    return "ok"
```

## ¿Cómo evito el error 131026?

* **Valida los números al capturarlos**, en formato internacional con código de país.
* **Haz que el contacto te escriba primero por WhatsApp** cuando puedas, con un enlace "Escríbenos
  por WhatsApp": un número que ya te escribió es un número que recibe.
* **Escucha el webhook `message_status`** en lugar de la respuesta del envío: un `200` significa
  "aceptado por Meta", no "entregado".
* **Ten un canal de respaldo** para los mensajes críticos, como los códigos de inicio de sesión. La
  [guía de OTP por WhatsApp en Node.js](https://wa.genuka.com/es/docs/guides/whatsapp-otp-nodejs) lo tiene previsto.

## Códigos de error relacionados

* [131050](https://wa.genuka.com/es/docs/errors/131050): el destinatario sí recibe WhatsApp, pero dejó de recibir tus
  mensajes de marketing.
* [131049](https://wa.genuka.com/es/docs/errors/131049): un mensaje de marketing retenido por Meta para este
  destinatario, que puedes volver a intentar más tarde.
* [131047](https://wa.genuka.com/es/docs/errors/131047): la ventana de 24 horas está cerrada; una plantilla sí pasará.

## Preguntas frecuentes

### ¿Debo reintentar un envío que falló con 131026?

No por WhatsApp. Mientras la situación del destinatario no cambie (WhatsApp instalado, aplicación
actualizada, términos aceptados), el mismo envío fallará.

### ¿Por qué la respuesta del envío fue 200 si el mensaje falló?

Porque Meta aceptó la solicitud antes de intentar la entrega. Meta indica que sus errores vuelven
en la respuesta, por webhook o de ambas formas, y recomienda vigilar las dos. Un 131026 llega casi
siempre por el webhook de estado.

### ¿Cómo encuentro los destinatarios con 131026 de una campaña?

`GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000` enumera los destinatarios
fallidos con el mensaje de Meta, 200 de forma predeterminada y 1.000 como máximo, sin paginación.
El código numérico llega por el webhook `message_status`: guárdalo ahí si quieres filtrar por
causa; es la única lista completa para una campaña grande.

### ¿Se cobra un mensaje que falló con 131026?

Meta no lo cobra, ya que solo cobra un mensaje de plantilla cuando se entrega
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Del lado de Genuka WA, en cambio, un envío que Meta aceptó cuenta contra la cuota de tu
suscripción aunque la entrega falle después: quita los números no localizables de tus próximos
envíos.

## Fuentes

* [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)
