Statuts des webhooks WhatsApp : envoyé, distribué, lu, échoué
Les webhooks de statut signalent ce qui est arrivé à un message envoyé par une entreprise via la Cloud API de WhatsApp. Ils arrivent sur le champ messages, avec un tableau statuses au lieu d'un tableau messages : sent (une coche), delivered (deux coches), read (deux coches bleues), played pour les messages vocaux, et failed avec un tableau errors. Faites correspondre statuses[].id au wamid renvoyé par votre requête d'envoi.
easyCoexistence connecte le numéro WhatsApp Business que vous utilisez déjà à la Cloud API de Meta via Coexistence.
Valeurs de statut envoyées par Meta : sent, delivered, read, played (première lecture des messages vocaux) et failed.
Webhooks de statut distincts qu'un message sortant peut produire : sent, delivered et read.
Depuis cette version de la Graph API, l'objet conversation est omis, sauf pour les messages dans une fenêtre de point d'entrée gratuit.
Aucune API ne permet de récupérer les anciennes données de webhook ; Meta demande de capturer et stocker les payloads à leur arrivée.
L'en-tête X-EC-Event sur un statut transféré : les statuts voyagent dans les événements messages, sous value.statuses.
Où arrivent les webhooks de statut WhatsApp ?
Sur le même champ messages que celui qui transporte les messages des clients, dans le même objet, avec la même enveloppe entry et changes. La différence se situe dans value : un message entrant a un tableau messages, un statut a un tableau statuses. Un gestionnaire qui ne lit que value.messages perd chaque statut sans aucune erreur. metadata.phone_number_id indique lequel de vos numéros a envoyé le message, et un tableau contacts avec le nom de profil du client, son wa_id et son BSUID est fourni, sauf sur les statuts failed et sur le statut sent des messages de groupe. Voici l'exemple Meta d'un template marketing ayant quitté les serveurs de Meta :
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}Que signifie chaque valeur de statut ?
Chaque valeur correspond à une marque que le client verrait dans WhatsApp. Un statut n'est considéré comme lu qu'après avoir été distribué, et lorsqu'un client reçoit un message alors que la conversation est déjà ouverte, Meta envoie read sans webhook delivered préalable, par optimisation interne. Un outil de suivi doit donc accepter read même si delivered n'est jamais arrivé, et classer les statuts plutôt que de les attendre un par un dans un ordre fixe.
Quels champs porte un objet de statut ?
Moins qu'un message, et plusieurs sont conditionnels. La référence de Meta indique quand chacun est présent :
- id : le wamid du message que vous avez envoyé, la clé de rapprochement.
- status et timestamp : la valeur et l'heure Unix à laquelle le webhook a été déclenché, sous forme de chaîne.
recipient_id: le numéro de téléphone ou l'identifiant de groupe, omis lorsque vous avez envoyé à un BSUID et que le numéro est indisponible.recipient_user_id: le BSUID du client, omis sur un statut failed lorsque vous avez envoyé à un numéro de téléphone.recipient_typeetrecipient_participant_id: uniquement pour les messages envoyés à un groupe.biz_opaque_callback_data: uniquement si vous l'avez défini dans la requête d'envoi.- pricing : uniquement sur sent et sur l'un de delivered ou read. errors : uniquement sur failed.
Comment rapprocher un statut du message envoyé ?
Par le wamid. La requête d'envoi répond avec messages[0].id, et chaque statut de ce message porte la même valeur dans statuses[].id. Conservez-le à côté de votre propre enregistrement lors de l'envoi, puis mettez-le à jour à l'arrivée des statuts, en gardant le statut le plus avancé atteint, afin qu'un delivered tardif n'écrase pas read. Un statut dont vous ne connaissez pas le wamid a été envoyé par autre chose sur le numéro, comme une automatisation, et peut être ignoré ou journalisé.
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Qu'est-ce qui change sur un numéro Coexistence ?
Les statuts décrivent ce qui a été envoyé via l'API : réponses de vos automatisations, messages de votre IA envoyés via un connecteur MCP, et tout ce que votre propre code envoie. Ce que le propriétaire tape dans l'application WhatsApp Business arrive autrement, sous forme de smb_message_echoes, que Meta documente comme le miroir des messages envoyés depuis l'application. Les messages importés lors de l'import unique de l'historique portent leur propre statut dans le webhook d'historique, avec des valeurs telles que delivered, read, played, pending et error.
Les statuts suivent le même chemin que le champ messages du numéro. Avec une destination directe, Meta les envoie directement à votre endpoint, car messages est un champ que Meta permet de remplacer par une destination. Avec les automatisations activées et une Forward URL définie, ils atteignent cette URL sous forme d'événements messages.
Comment votre IA ou votre automatisation sait-elle qu'un message a été distribué ?
Par votre destination, pas par l'envoi. Lorsqu'un assistant appelle send_template ou send_message, le résultat de l'outil contient le wamid et indique que Meta a accepté le message ; la distribution est confirmée plus tard, sur l'appareil du client, et remontée sous forme de statut. easyCoexistence ne conserve aucun historique de statuts à interroger, et aucun outil MCP ne lit les statuts : un agent qui a besoin de la confirmation de distribution doit donc envoyer via votre système, ou lire les statuts que reçoit votre Forward URL.
Il en va de même pour les automatisations : une exécution dans l'onglet Runs affiche l'étape de réponse comme terminée dès que Meta a accepté le message, et un échec signalé ensuite n'apparaît que comme statut failed chez votre destination.
Erreurs courantes
- Chercher un champ statuses séparé. Les statuts arrivent dans messages : un gestionnaire qui ne lit que value.messages les perd sans aucune erreur.
- Exiger delivered avant read. Meta omet le webhook delivered lorsque le message est lu dès son arrivée.
- Considérer la réponse d'envoi comme une distribution. Un wamid signifie que Meta a accepté la requête ; un échec peut suivre des minutes plus tard sous forme de statut failed.
- Identifier les clients par recipient_id seul. Il est omis lorsque vous avez envoyé à un BSUID et que le numéro est indisponible ; c'est recipient_user_id qui porte le BSUID.
Les statuts de ce que vos automatisations, votre IA ou votre code envoient arrivent sur votre serveur : directement depuis Meta en mode direct, ou transférés vers votre Forward URL et signés avec X-EC-Signature lorsque les automatisations sont activées, et ils ne sont pas stockés par défaut. De US$ 9 à US$ 0,75 par numéro et par mois, dégressif à mesure que vous ajoutez des numéros, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Les webhooks de statut incluent-ils le texte du message ?
Non. Un statut porte le wamid, le statut, le destinataire, les horodatages et, le cas échéant, la tarification et les erreurs. Conservez votre propre copie de ce que vous avez envoyé, indexée par le wamid, si vous devez l'afficher à côté de son statut.
Puis-je récupérer plus tard les anciens statuts auprès de Meta ?
Non. Le guide des webhooks de Meta indique qu'il n'existe aucune API pour récupérer les données de webhook historiques ; un statut que votre endpoint n'a pas capturé est donc perdu une fois que Meta cesse de réessayer, au bout de 7 jours au maximum.
À quoi sert biz_opaque_callback_data ?
C'est une chaîne que vous définissez à l'envoi, comme l'identifiant de votre commande ou de votre ticket. Meta la renvoie dans les statuts de ce message, ce qui vous permet de rapprocher un statut de votre enregistrement sans rechercher d'abord le wamid.
Dois-je répondre 200 aux webhooks de statut ?
Oui, comme pour tout POST de webhook. Meta considère toute autre réponse comme une distribution échouée et la renvoie, ce qui est l'une des façons dont un même statut vous parvient deux fois.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le