Genuka WA docs

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

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):

"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ónVersión mínima
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

El título que acompaña al código en el campo message es "Message Undeliverable" (lista de 360dialog). 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.

CanalQué recibes
Webhook message_statusdata.status: "failed", data.errors[0].code: 131026
Respuesta de POST /api/v1/messages, cuando Meta rechaza durante la llamada400, "error": "send_recipient_permanent", meta.code: 131026
CampañaEl destinatario pasa a failed, con el mensaje de Meta en errorMessage; nunca se reintenta
Panel, sección Bandeja de entradaLa burbuja fallida; "Ver por qué" muestra el código y los detalles de Meta
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?

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.

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".

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.

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.

// 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");
}

¿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 lo tiene previsto.

Códigos de error relacionados

  • 131050: el destinatario sí recibe WhatsApp, pero dejó de recibir tus mensajes de marketing.
  • 131049: un mensaje de marketing retenido por Meta para este destinatario, que puedes volver a intentar más tarde.
  • 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). 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

En esta página