# Recevoir les réactions WhatsApp

Abonnez-vous aux changements de réaction pour savoir quand un contact ajoute un emoji à l'un de vos messages, le modifie ou le retire. Les réactions annotent un message existant et arrivent via `whatsapp.reacted`.

## Prérequis

Configurez un [endpoint de webhook](/docs/guides/webhooks) pour votre espace de travail. Pour récupérer les réactions actuelles ou leur historique, utilisez une clé API avec la permission de lecture WhatsApp.

## 1. S'abonner aux changements de réaction

Ajoutez `whatsapp.reacted` à votre abonnement webhook. Un abonnement à `whatsapp.received` n'inclut pas les réactions. Suivez le [guide des webhooks](/docs/guides/webhooks) pour la vérification de signature, les réessais de livraison et la configuration de l'endpoint.

Les réactions ne créent pas de nouveau message dans la liste des messages et n'ouvrent pas de fenêtre de service client. Si vous devez répondre, vérifiez les [règles de fenêtre de service](/docs/guides/whatsapp/sending-whatsapp) avant d'envoyer un message libre.

## 2. Identifier le message et le changement

Lisez le `data.whatsapp_id` de l'événement pour trouver le message auquel le contact a réagi. Il s'agit de l'ID de message Bird d'origine (`wam_…`), et non d'un ID de réaction distinct.

Utilisez `data.from` pour identifier le contact et `data.to` pour identifier votre expéditeur WhatsApp. Ce sont des objets d'adresse WhatsApp ; gérez les [identifiants utilisateur limités à l'entreprise](/docs/guides/whatsapp/business-scoped-user-ids) lorsque l'adresse du contact n'a pas de numéro de téléphone.

Un contact ajoutant une réaction pouce levé produit ce webhook :

```json
{
  "data": {
    "emoji": "👍",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-08-28T19:01:10.000Z",
  "type": "whatsapp.reacted"
}
```

Interprétez `data.emoji` comme suit :

- Un emoji non nul ajoute ou remplace la réaction de ce contact sur le message référencé.
- Un emoji `null` supprime la réaction de ce contact. Le champ est présent lors d'un événement de suppression.

Un remplacement arrive sous la forme d'un seul événement portant le nouvel emoji ; il n'y a pas d'événement de suppression distinct pour l'ancien emoji. Conservez la chaîne exacte : `❤` et `❤️` sont des valeurs distinctes dans le payload.

## 3. Récupérer les réactions actuelles

Si votre application affiche la réaction actuellement attachée à un message, [récupérez le message](/docs/api/reference/get-whatsapp-message) et lisez son `reactions`. La liste contient une réaction en vigueur par expéditeur et est omise quand aucune réaction ne subsiste.

Pour `GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te`, les champs liés aux réactions ont cette forme (autres champs du message omis) :

```json
{
  "id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
  "reactions": [
    {
      "emoji": "👍",
      "from": { "phone_number": "+14155550100" }
    }
  ]
}
```

Le message conserve son contenu d'origine, sa direction et son statut de livraison. `reactions[].from` identifie la personne qui a réagi.

Ne considérez pas le dernier webhook reçu comme l'état actuel. WhatsApp rapporte les horaires de réaction à la seconde près, donc des changements peuvent partager un horodatage, et les réessais de webhook peuvent modifier l'ordre d'arrivée. Utilisez les webhooks pour déclencher une actualisation des réactions actuelles du message.

## 4. Consulter l'historique des réactions

[Listez les événements de réaction](/docs/api/reference/list-whatsapp-message-reaction-events) pour inspecter les changements sur le message référencé. Les changements entrants d'un contact ont le statut `received` ; une suppression porte `emoji: null`. La liste inclut aussi les résultats des [réactions envoyées par votre espace de travail](/docs/guides/whatsapp/reactions).

L'endpoint reaction-events API renvoie une réponse paginée. Cet exemple montre une réaction d'entreprise rejetée et une réaction de contact reçue antérieurement :

```json
{
  "data": [
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mh",
      "emoji": "🎉",
      "status": "rejected",
      "from": {
        "phone_number": "+13124495569"
      },
      "error": {
        "code": "internal_error",
        "description": "the receiving number is no longer connected",
        "occurred_at": "2026-08-28T19:04:22Z"
      },
      "occurred_at": "2026-08-28T19:04:22Z"
    },
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mg",
      "emoji": "👍",
      "status": "received",
      "from": {
        "phone_number": "+14155550100",
        "bsuid": "US.13491208655302741918"
      },
      "occurred_at": "2026-08-28T19:01:10Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0"
}
```

L'historique des réactions est distinct des événements de livraison du message. L'endpoint message-events ne contient pas les changements `whatsapp.reacted`. Pour la rétention et la pagination, suivez la [référence du journal des réactions](/docs/api/reference/list-whatsapp-message-reaction-events).

## Dépannage

- **Pas de webhook de réaction** : Vérifiez que l'abonnement inclut `whatsapp.reacted`. Une réaction à un message ancien dont la référence fournisseur ne peut plus être résolue ne produit aucune réaction associée, aucune entrée de journal, ni aucun webhook.
- **Réaction absente de la liste des messages** : Consultez le message d'origine. Une réaction y est rattachée et n'a pas de ligne de message distincte.
- **L'état de la réaction change de façon inattendue** : Actualisez le `reactions` du message d'origine au lieu d'ordonner les événements webhook par heure d'arrivée ou horodatage.

## Étapes suivantes

- [Envoyer ou supprimer une réaction](/docs/guides/whatsapp/reactions)
- [Lire les payloads d'événements WhatsApp](/docs/guides/whatsapp/events)
- [Recevoir des messages WhatsApp](/docs/guides/whatsapp/receiving-whatsapp)

## 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](/products/whatsapp) (product)

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