Erreur WhatsApp 131026 : message non délivrable

L'erreur WhatsApp 131026 signifie que Meta n'a pas pu remettre le message au destinataire : son numéro n'est pas sur WhatsApp, il n'a pas accepté les dernières conditions d'utilisation, ou son application est trop ancienne. Ne réessayez pas sur WhatsApp : vérifiez le numéro, puis joignez la personne par un autre canal.

Que signifie l'erreur 131026 ?

Meta la décrit ainsi (codes d'erreur 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. »

Trois causes possibles, donc, toutes du côté du destinataire. Pour la troisième, Meta donne les versions minimales de l'application :

Le titre qui accompagne le code dans le champ message est « Message Undeliverable » (liste de 360dialog). Il décrit le symptôme, pas la cause : c'est le code et error_data.details qui la donnent.

Quand l'erreur 131026 apparaît-elle ?

• Le numéro n'a pas de compte WhatsApp : une ligne fixe, un numéro de standard, une faute de frappe dans un formulaire.
• Le numéro est mal formaté : sans + ni indicatif pays, un numéro local peut être interprété dans le mauvais pays et tomber sur une personne qui n'a pas WhatsApp. Écrivez toujours to au format international, par exemple +237690000001.
• L'application du destinataire n'est pas à jour, ou il n'a pas validé les nouvelles conditions d'utilisation.

Où la voir dans Genuka WA ?

Le cas le plus courant : Meta accepte l'envoi, puis signale l'échec dans le webhook de statut.

{
  "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 est l'objet de statut de Meta, transmis intact : error_data.details dépend du cas et peut préciser la cause.

Comment corriger l'erreur 131026 ?

// 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)) {
      // À vous d'écrire cette fonction : le contact passe sur SMS/email jusqu'à son prochain message.
      void markWhatsAppUnreachable(event.data.recipient_id);
    }
  }
  return new Response("ok");
}

Comment éviter l'erreur 131026 ?

• Validez les numéros à la saisie, au format international avec indicatif pays.
• Faites venir le contact sur WhatsApp en premier quand c'est possible, par un lien « Écrivez-nous sur WhatsApp » : un numéro qui vous a déjà écrit est un numéro qui reçoit.
• Écoutez le webhook message_status plutôt que la réponse d'envoi : un 200 veut dire « accepté par Meta », pas « livré ».
• Gardez un canal de repli pour les messages critiques, comme les codes de connexion. Le guide OTP WhatsApp en Node.js prévoit ce repli.

Quels codes sont liés ?

• 131050 : le destinataire reçoit bien WhatsApp, mais a refusé vos messages marketing.
• 131049 : message marketing retenu par Meta pour ce destinataire, à retenter plus tard.
• 131047 : la fenêtre de 24 heures est fermée ; un template passera.

FAQ

Faut-il réessayer un envoi en 131026 ?

Non, pas sur WhatsApp. Tant que le destinataire n'a pas changé de situation (installé WhatsApp, mis à jour son application, accepté les conditions), le même envoi échouera.

Pourquoi la réponse d'envoi est-elle 200 alors que le message a échoué ?

Parce que Meta a accepté la requête avant de tenter la livraison. Meta indique que ses erreurs arrivent soit dans la réponse, soit par webhook, soit les deux, et recommande de surveiller les deux. L'échec 131026 arrive le plus souvent dans le webhook de statut.

Comment retrouver les destinataires en 131026 dans une campagne ?

GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000 liste les destinataires en échec avec le message de Meta, 200 par défaut et 1 000 au plus, sans pagination. Le code numérique, lui, arrive dans le webhook message_status : c'est lui qu'il faut stocker si vous voulez filtrer par cause, et c'est la seule liste complète pour une grosse campagne.

Un message en échec 131026 est-il facturé ?

Pas par Meta, qui ne facture un template que lorsqu'il est livré (Meta, Pricing). Côté Genuka WA, en revanche, un envoi accepté par Meta compte dans le quota de votre abonnement, même si la livraison échoue ensuite : écartez les numéros injoignables de vos prochains envois.

Sources

• Meta — Error codes
• Meta — Status webhook reference
• Meta — Pricing
• 360dialog — API error message list