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 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 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 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 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 :

Exemple de code

{
  "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 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) :

Exemple de code

{
  "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 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.

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 :

Exemple de code

{
  "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.

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

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation