Statut de distribution WhatsApp : le guide technique Cloud API

Un statut de distribution WhatsApp est une notification d'événement asynchrone transmise par webhook depuis les serveurs de Meta vers votre système, indiquant l'état précis d'un message : envoyé (sent), distribué sur l'appareil du destinataire (delivered), lu (read) ou échoué (failed). Le suivi systématique de ces états permet aux équipes d'ingénierie et aux plateformes e-commerce d'identifier immédiatement les numéros invalides, les blocages et les pannes réseau avant qu'ils ne dégradent l'expérience client ou le chiffre d'affaires. Ce guide analyse l'architecture des statuts de la WhatsApp Cloud API, la structure des données reçues et les mécanismes d'automatisation pour traiter les échecs de distribution en temps réel.

Les quatre étapes du cycle de vie d'un message dans l'API WhatsApp Cloud

Chaque message sortant expédié via l'API suit un cycle déterministe entre votre infrastructure, les passerelles de Meta et le terminal du destinataire. Après l'envoi d'une requête HTTP POST sur le point de terminaison des messages, l'API renvoie une réponse synchrone confirmant la prise en charge de la charge utile, accompagnée d'un identifiant unique de message (wamid). À partir de cet instant, l'évolution de l'acheminement est notifiée exclusivement au moyen de requêtes webhook asynchrones.

Le tableau ci-dessous détaille les quatre statuts standardisés, leur signification technique et l'action opérationnelle correspondante :

Statut API	Signification technique	Indicateur dans l'application	Action système requise
sent	Le message est traité et mis en file d'attente chez Meta	Coche grise unique	Requête validée. Aucune action requise.
delivered	Le message a été réceptionné par l'appareil cible	Double coche grise	Terminal connecté. Le message est en attente d'ouverture.
read	Le destinataire a ouvert la conversation	Double coche bleue	Exposition confirmée. Événement déclencheur pour les relances.
failed	Échec d'acheminement avec code d'erreur	Point d'exclamation rouge	Rupture de livraison. Traitement du code d'erreur et bascule.

La distinction entre sent et delivered est structurelle : l'état sent confirme uniquement que les infrastructures de Meta ont accepté le message. Si le téléphone de l'utilisateur final est hors tension, privé de connexion Internet ou si la carte SIM est inactive, le message reste bloqué au statut sent jusqu'à expiration de sa durée de validité (TTL), fixée à 30 jours par Meta.

Analyse des données webhook et détection du statut de distribution en temps réel

À chaque transition d'état, Meta émet une requête HTTP POST vers l'URL de rappel configurée dans votre application. Le corps JSON contient les identifiants nécessaires pour réconcilier le statut avec votre base de données locale. L'ensemble des paramètres d'événement est documenté dans la référence des composants Webhooks de Meta.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "33100000000",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "statuses": [{
          "id": "wamid.HBgLMTY1...",
          "status": "delivered",
          "timestamp": "1711200000",
          "recipient_id": "33600000000",
          "conversation": {
            "id": "CONVERSATION_ID",
            "origin": {
              "type": "utility"
            }
          },
          "pricing": {
            "billable": true,
            "pricing_model": "CBP",
            "category": "utility"
          }
        }]
      },
      "field": "messages"
    }]
  }]
}

Le traitement de ces flux impose de respecter trois contraintes d'architecture logicielle :

1. L'ordre d'arrivée n'est pas garanti : En raison du routage distribué à travers le réseau mondial de Meta, un événement read peut atteindre votre passerelle quelques millisecondes avant l'événement delivered. Votre base de données doit implémenter un verrouillage optimiste ou une machine à états interdisant l'écrasement d'un statut avancé par un événement antérieur retardé.
2. Confidentialité de l'utilisateur final : Si le destinataire a désactivé les accusés de lecture dans ses paramètres WhatsApp, Meta ne transmettra jamais de webhook read. Le statut terminal pour ce contact restera delivered, même s'il interagit ultérieurement avec vos interfaces.
3. Facturation à la conversation : Le webhook de statut transporte l'objet pricing. Le premier événement sent à l'intérieur d'une fenêtre de 24 heures matérialise la catégorie de la conversation (Utility, Marketing ou Service) et verrouille le modèle tarifaire facturé par Meta.

Gestion des pannes lorsque le statut de distribution WhatsApp passe à failed

Le statut critique pour toute intégration transactionnelle est failed. En cas de rupture d'acheminement, la charge utile envoyée par Meta incorpore un tableau errors contenant un code numérique et une description textuelle. Vous pouvez consulter l'inventaire exhaustif des statuts d'erreur sur la documentation des codes d'erreur Meta.

"statuses": [{
  "id": "wamid.HBgLMTY1...",
  "status": "failed",
  "timestamp": "1711200005",
  "recipient_id": "33600000000",
  "errors": [{
    "code": 131026,
    "title": "Message Undeliverable",
    "message": "Message Undeliverable.",
    "error_data": {
      "details": "Receiver is incapable of receiving this message"
    }
  }]
}]

Les échecs de distribution récurrents se concentrent sur trois codes principaux :

• Code 131026 (Message Undeliverable) : Ce code indique que le numéro n'est pas enregistré sur WhatsApp, que le compte professionnel a été bloqué par l'utilisateur, ou que les contrôles de conformité de Meta ont stoppé l'envoi. Tout rejeu immédiat vers ce numéro doit être suspendu.
• Code 131047 (Re-engagement Required) : Ce refus survient lors d'une tentative d'envoi d'un message libre hors de la fenêtre d'assistance de 24 heures. La seule correction consiste à initier le contact via un modèle de message (Template Message) validé.
• Code 130429 (Rate Limit Exceeded) : Le débit alloué à votre numéro de téléphone a été dépassé. Le système doit absorber la charge et temporiser via un algorithme de réessai progressif (Exponential Backoff).

Optimisation du support client e-commerce grâce au monitoring proactif des erreurs

Sur les plateformes connectées à des solutions de commerce en ligne comme WooCommerce ou Shopify, une rupture de livraison sur une confirmation de commande ou un lien de suivi colis crée immédiatement une friction client et engendre des tickets de support évitables.

La surveillance programmatique des statuts permet de déployer une logique de résilience à trois niveaux :

1. Bascule multicanale automatique (Fallback SMS) : Dès réception d'un statut failed sur une notification transactionnelle critique, un worker d'arrière-plan intercepte le message et l'achemine via un opérateur SMS sans intervention humaine.
2. Assainissement continu du CRM : L'identification automatisée des erreurs permanentes (telles que le code 131026) permet d'étiqueter les fiches clients corrompues, de purger les bases de diffusion marketing et de protéger la note de qualité (Quality Rating) attribuée par Meta.
3. Escalade préventive : Si l'acheminement d'un avis d'expédition échoue, un ticket est ouvert au support technique avec les détails de l'erreur avant même que l'acheteur ne constate l'absence de notification.

Architecture technique : concevoir une infrastructure de webhooks résiliente

Pour ingérer les statuts de distribution à haute fréquence sans perte de données, votre architecture d'écoute doit respecter trois standards d'ingénierie :

1. Réponse synchrone et découplage : Les serveurs de Meta exigent une réponse HTTP 200 OK en moins de 3 secondes sous peine de réémettre les requêtes jusqu'à saturation. Le récepteur doit valider la requête, stocker la charge brute dans une file de messages (telle que Redis Streams ou RabbitMQ) et retourner immédiatement le statut 200, laissant le traitement métier à des processus asynchrones dédiés.
2. Idempotence stricte : Les protocoles de transport réseau génèrent fréquemment des doublons. L'application doit maintenir une table d'idempotence basée sur le couple wamid et status pour garantir qu'un événement identique réémis ne déclenche pas deux fois la même logique d'entreprise.
3. Vérification cryptographique de la charge : Afin d'éliminer tout risque d'injection, chaque requête entrante doit être authentifiée en recalculant la signature HMAC-SHA256 du corps brut avec le secret d'application Meta, et en la comparant à l'en-tête X-Hub-Signature-256.

Une infrastructure de messagerie robuste garantit des taux de délivrabilité optimaux et protège la réputation de vos numéros professionnels. Pour évaluer la résilience de vos passerelles API ou mettre en place une architecture d'automatisation sur mesure, contactez nos ingénieurs pour obtenir un audit technique approfondi.

Questions fréquentes

Pourquoi un message reste-t-il au statut sent sans passer à delivered ?

Un message WhatsApp reste à l'état sent lorsque les serveurs de Meta l'ont validé et pris en charge, mais qu'il n'a pas encore atteint l'appareil final. Cette situation survient si le téléphone du client est éteint, hors ligne, en mode avion ou si sa carte SIM est désactivée. Meta réessaye d'acheminer le message pendant une période maximale de 30 jours avant expiration.

Peut-on savoir si un message a été lu si le destinataire a désactivé les confirmations de lecture ?

Non. Lorsqu'un utilisateur désactive les confirmations de lecture dans les paramètres de confidentialité de son application WhatsApp, Meta ne transmet aucun événement read par webhook pour les messages individuels. Le statut le plus avancé reçu par votre système restera delivered, sauf si l'utilisateur envoie une réponse active dans la conversation, attestant ainsi de sa lecture.

Quelle est la différence entre l'erreur 131026 et un échec temporaire de l'API Meta ?

Le code d'erreur 131026 signale un échec définitif de distribution : le numéro n'utilise pas WhatsApp, a bloqué votre compte professionnel ou enfreint les politiques d'intégrité de Meta. Aucun nouvel envoi ne doit être tenté. En revanche, les erreurs temporaires comme le code 130429 (dépassement des limites de débit) nécessitent une pause et une reprise progressive via un algorithme de backoff exponentiel.

Pourquoi les événements webhook arrivent-ils parfois dans le désordre chronologique ?

Meta utilise une infrastructure distribuée à l'échelle mondiale pour acheminer ses notifications. En fonction des chemins de routage et de la latence réseau, un événement read peut parvenir à votre serveur quelques millisecondes avant l'événement delivered. Votre application doit intégrer une logique conditionnelle pour empêcher qu'un événement antérieur n'écrase un état plus avancé dans votre base de données.