Receiving WhatsApp reactions

Subscribe to reaction changes to learn when a contact adds an emoji to one of your messages, changes it, or takes it back. Reactions annotate an existing message and arrive through whatsapp.reacted.

Prerequisites

Set up a webhook endpoint for your workspace. To retrieve the current reactions or their history, use an API key with WhatsApp read permission.

Add whatsapp.reacted to your webhook subscription. A subscription to whatsapp.received does not include reactions. Follow the webhooks guide for signature verification, delivery retries, and endpoint configuration.

Reactions do not create a new message in the message list or open a customer service window. If you need to reply, check the service window rules before sending a free-form message.

2. Identify the message and the change

Read the event's data.whatsapp_id to find the message the contact reacted to. This is the original Bird message ID (wam_…), rather than a separate reaction ID.

Use data.from to identify the contact and data.to to identify your WhatsApp sender. These are WhatsApp address objects; handle business-scoped user IDs when the contact's address has no phone number.

A contact adding a thumbs-up reaction produces this webhook:

Code example

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

Interpret data.emoji as follows:

A non-null emoji adds or replaces that contact's reaction on the referenced message.
A null emoji removes that contact's reaction. The field is present on a removal event.

A replacement arrives as one event carrying the new emoji; there is no separate removal event for the old emoji. Preserve the exact string: ❤ and ❤️ are distinct values in the payload.

3. Retrieve the current reactions

If your application displays the reaction currently attached to a message, retrieve the message and read its reactions. The list contains one standing reaction per sender and is omitted when no reactions stand.

For GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te, the reaction-related fields have this shape (other message fields omitted):

Code example

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

The message retains its original content, direction, and delivery status. reactions[].from identifies the person who reacted.

Do not treat the last webhook you receive as the current state. WhatsApp reports reaction times to the second, so changes can share a timestamp, and webhook retries can change arrival order. Use webhooks to trigger a refresh of the message's current reactions.

4. Inspect reaction history

List reaction events to inspect changes to the referenced message. Incoming contact changes have status received; a removal carries emoji: null. The list also includes outcomes of reactions your workspace sent.

The reaction-events API returns a paginated response. This example shows a rejected business reaction and an earlier received contact reaction:

Code example

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

Reaction history is separate from the message's delivery events. The message-events endpoint does not contain whatsapp.reacted changes. For retention and pagination, follow the reaction log reference.

Troubleshooting

No reaction webhook: Check that the subscription includes whatsapp.reacted. A reaction to an older message whose provider reference can no longer be resolved produces no matched reaction, log entry, or webhook.
Reaction missing from the message list: Look up the original message. A reaction is attached to it and has no separate message row.
Reaction state changes unexpectedly: Refresh the original message's reactions instead of ordering webhook events by arrival time or timestamp.

Next steps

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideConnecting WhatsApp to Bird: from buying a number to a live channel Understand the conceptWhat is the 24-hour customer service window on WhatsApp?Use the toolWhatsApp message builder Explore the capabilityWhatsApp

Try the practice and get an implementation brief