# Événements de statut des messages WhatsApp

Bird enregistre des **événements** pour les messages WhatsApp entrants et sortants. Une chronologie sortante montre ce qui s'est passé après qu'un envoi a renvoyé `202` : acceptation, transfert vers WhatsApp, livraison, lecture ou échec. Une chronologie entrante enregistre le moment où Bird a reçu le message.

Cette page explique comment lire cette chronologie via l'API. Pour que Bird envoie chaque événement à votre endpoint au moment où il se produit, consultez [Webhooks de statut des messages](/docs/guides/whatsapp/webhooks/message-status). Les réactions ont leur propre historique, décrit dans [Événements de réaction](/docs/guides/whatsapp/events/reactions).

## Événements du cycle de vie

Les événements apparaissent dans l'ordre chronologique. Un message sortant peut s'arrêter à [`whatsapp.failed` ou `whatsapp.rejected`](#événements-déchec), et son événement `whatsapp.read` n'apparaît que si le destinataire ouvre le message. Une chronologie entrante commence par `whatsapp.received` et peut enregistrer `whatsapp.read` après que votre espace de travail a marqué le message comme lu.

| Événement            | Signification                                                          |
| -------------------- | ---------------------------------------------------------------------- |
| `whatsapp.accepted`  | Bird a accepté la demande d'envoi. C'est ce que `202` a signalé.       |
| `whatsapp.sent`      | Bird a transmis le message au réseau WhatsApp.                         |
| `whatsapp.delivered` | WhatsApp a confirmé la livraison sur l'appareil du destinataire.       |
| `whatsapp.read`      | Le destinataire a ouvert le message.                                   |
| `whatsapp.failed`    | Le message n'a pas été livré. `error.code` indique ce qui l'a empêché. |
| `whatsapp.rejected`  | Bird a refusé le message avant de l'envoyer. Il n'a pas été facturé.   |
| `whatsapp.received`  | Bird a reçu un message entrant d'un contact.                           |

Les callbacks `delivered` ou `read` applicables peuvent déclencher la part Meta du prix. Les payloads d'événement WhatsApp ne comportent aucun coût. Relisez le message avec [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) pour voir ce qu'il a coûté. Voir [Coût et facturation](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing).

[Marquer un message entrant comme lu](/docs/guides/whatsapp/mark-message-as-read) enregistre `whatsapp.read` dans sa chronologie mais n'émet pas de webhook d'accusé de lecture. Le message entrant conserve son statut `received` et enregistre `read_at` après que WhatsApp a accepté l'accusé.

`whatsapp.read` ne change **pas** le `status` du message. Un message livré reste `delivered` ; le message enregistre aussi la lecture dans `read_at`.

**`whatsapp.delivered` peut être entièrement absent.** Lorsque le destinataire a déjà la conversation ouverte sur son appareil, Meta signale la lecture sans jamais signaler de livraison ; la chronologie se lit donc `whatsapp.accepted` → `whatsapp.sent` → `whatsapp.read` sans `whatsapp.delivered` entre les deux. Traitez `read` comme preuve de livraison : un consommateur qui attend `delivered` avant de considérer le message arrivé restera bloqué précisément sur les destinataires qui l'ont vu le plus vite, et un consommateur qui calcule un taux de livraison à partir de `delivered` seul le sous-estime. Le `status` du message reste `sent` dans ce cas, car seul un accusé de livraison le fait avancer.

Un callback de lecture seul peut quand même déclencher les frais Meta applicables. Bird utilise une même identité de frais pour les chemins de livraison et de lecture ; l'absence d'événement de livraison n'implique pas une composante Meta gratuite. Voir [Coût et facturation](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing).

La liste des types d'événements est ouverte : de nouveaux types peuvent être ajoutés au fil du temps, traitez donc une valeur non reconnue comme un événement futur plutôt que comme une erreur.

## Événements d'échec

`whatsapp.failed` et `whatsapp.rejected` sont terminaux. Un **rejet** signifie que Bird a arrêté le message avant de l'envoyer à WhatsApp, il n'a donc pas été facturé. Les causes incluent un [destinataire supprimé ou désinscrit](/docs/guides/whatsapp/opt-outs), un solde de portefeuille insuffisant ou une destination sans prix configuré. Un **échec** signifie que le message n'a pas été livré, et `error.code` indique qui en a décidé. La plupart des codes portent le verdict de WhatsApp, mappé à partir du code signalé. `internal_error` est l'exception : il enregistre l'absence d'identifiant d'expéditeur utilisable ou l'épuisement des réessais de traitement. Une tentative de transport incertaine ne prouve pas que Meta n'a jamais reçu la requête. `meta_error_code` contient le code de WhatsApp lorsqu'il est disponible, et un échec `internal_error` n'en comporte aucun par construction.

Les deux événements contiennent un objet `error` avec un Bird `code` stable, un `description` lisible par l'humain, un `meta_error_code` optionnel et `occurred_at`. L'objet apparaît dans les enregistrements API et les payloads webhook uniquement pour ces types d'événements.

## Lecture des événements depuis API

`GET /v1/whatsapp/messages/{message_id}/events` renvoie la chronologie dans l'ordre chronologique. La liste bornée n'est pas paginée. La lecture des événements nécessite une clé API avec `whatsapp:read` :

**TypeScript**

```typescript
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);
```

Examples: [TypeScript](/fr-fr/documentation/guides/whatsapp/events/message-status.ts.md) · [Python](/fr-fr/documentation/guides/whatsapp/events/message-status.py.md) · [Go](/fr-fr/documentation/guides/whatsapp/events/message-status.go.md) · [PHP](/fr-fr/documentation/guides/whatsapp/events/message-status.php.md) · [CLI](/fr-fr/documentation/guides/whatsapp/events/message-status.cli.md) · [MCP](/fr-fr/documentation/guides/whatsapp/events/message-status.mcp.md) · [cURL](/fr-fr/documentation/guides/whatsapp/events/message-status.curl.md)

Un message qui a été accepté, envoyé, livré et lu renvoie quatre événements :

```json
{
  "data": [
    {
      "id": "ev_01ky7q6a1fejfbvs0myn41hj41",
      "occurred_at": "2026-07-23T14:48:34.71Z",
      "type": "whatsapp.accepted"
    },
    {
      "id": "ev_01ky7q6a2denvtd6jg1vqwmg13",
      "occurred_at": "2026-07-23T14:48:35.671Z",
      "type": "whatsapp.sent"
    },
    {
      "id": "ev_01ky7q6a2zff9r2qm74mmg1g6z",
      "occurred_at": "2026-07-23T14:48:36.642Z",
      "type": "whatsapp.delivered"
    },
    {
      "id": "ev_01ky7q6c21frssf0vj8h50qysw",
      "occurred_at": "2026-07-23T14:48:38.65Z",
      "type": "whatsapp.read"
    }
  ]
}
```

Passez `type` pour ne renvoyer qu'un seul type d'événement public, par exemple `?type=whatsapp.failed` ou `?type=whatsapp.read`. Omettez-le pour obtenir la chronologie complète.

Cette même chronologie est ce que la page [Journal WhatsApp](/docs/guides/whatsapp/message-log) affiche lorsque vous ouvrez un message.

![La fiche de détail du message WhatsApp dans le tableau de bord Bird, ouverte pour un message bird_delivery_update livré : l'onglet Events affichant la chronologie du cycle de vie par message (Accepted, Sent, Delivered et Read), chacun avec son temps écoulé et son horodatage, par-dessus la liste de messages grisée](/images/docs/dashboard-whatsapp-detail.png)

## Étapes suivantes

- [Webhooks de statut des messages](/docs/guides/whatsapp/webhooks/message-status) : recevoir chaque événement au moment où il se produit
- [Événements de réaction](/docs/guides/whatsapp/events/reactions) : lire les réactions actuelles et le journal des réactions
- [Marquer un message comme lu](/docs/guides/whatsapp/mark-message-as-read) : accuser réception d'un message entrant et afficher l'indicateur de saisie
- [Journal WhatsApp](/docs/guides/whatsapp/message-log) : la vue par message qui affiche cette chronologie
- [Envoi de messages WhatsApp](/docs/guides/whatsapp/sending-whatsapp) : là où le cycle de vie d'un message commence

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)