WhatsApp Business Platform

Interactive messages webhook reference

Updated: Aug 3, 2026
Copy for LLM
This reference describes trigger events and payload contents for the WhatsApp Business account messages webhook for interactive messages.
This page covers the list reply, button reply, and product payloads.

Triggers

Syntax

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_PROFILE_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>",
                "identity_key_hash": "<IDENTITY_KEY_HASH>" <!-- only included if identity change check enabled -->
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                  "id": "<CONTEXTUAL_WHATSAPP_MESSAGE_ID>"
                },
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "interactive",

                <!-- interactive list message replies only -->
                "interactive": {
                  "type": "list_reply",
                  "list_reply": {
                    "id": "<ROW_ID>",
                    "title": "<ROW_TITLE>",
                    "description": "<ROW_DESCRIPTION>"
                  }
                },

                <!-- interactive reply button message replies only -->
                "interactive": {
                  "type": "button_reply",
                  "button_reply": {
                    "id": "<BUTTON_ID>",
                    "title": "<BUTTON_LABEL_TEXT>"
                  }
                },

                <!-- product messages only -->
                "interactive": {
                  "type": "product",
                  "product": {
                    "retailer_id": "<PRODUCT_RETAILER_ID>",
                    "title": "<PRODUCT_TITLE>",
                    "description": "<PRODUCT_DESCRIPTION>",
                    "currency_code": "<PRODUCT_CURRENCY_CODE>",
                    "price_amount": <PRODUCT_PRICE_AMOUNT>,
                    "sale_price_amount": <PRODUCT_SALE_PRICE_AMOUNT>,
                    "url": "<PRODUCT_URL>"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Parameters

Placeholder Description Example value
<BUSINESS_DISPLAY_PHONE_NUMBER>
String
Business display phone number.
15550783881
<BUSINESS_PHONE_NUMBER_ID>
String
Business phone number ID.
106540352242922
<BUTTON_ID>
String
Button ID.
cancel-button
<BUTTON_LABEL_TEXT>
String
Button label text.
Cancel
<CONTEXTUAL_WHATSAPP_MESSAGE_ID>
String
WhatsApp message ID of the message containing the button the WhatsApp user tapped.
wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA=
<IDENTITY_KEY_HASH>
String
Identity key hash. Only included if you have enabled the identity change check feature.
DF2lS5v2W6x=
<PRODUCT_CURRENCY_CODE>
String
ISO 4217 currency code for the product price.
USD
<PRODUCT_DESCRIPTION>
String
Product description.
100% cotton, unisex fit
<PRODUCT_PRICE_AMOUNT>
Int
Product price multiplied by 1,000, so that the value is always a whole number. For example, a price of 1.00 USD is sent as 1000. Divide by 1,000 to get the actual price.
1000
<PRODUCT_RETAILER_ID>
String
Your own identifier for the product in your catalog. Labeled as Content ID in the Commerce Manager.
2lc20305pt
<PRODUCT_SALE_PRICE_AMOUNT>
Int
Discounted product price multiplied by 1,000, using the same format as price_amount. For example, a sale price of 0.80 USD is sent as 800. Included only when the product is on sale.
800
<PRODUCT_TITLE>
String
Product title.
Classic T-Shirt
<PRODUCT_URL>
String
URL of the product.
https://example.com/products/classic-t-shirt
<ROW_DESCRIPTION>
String
Row description.
Next Day to 2 Days
<ROW_ID>
String
Row ID.
priority_express
<ROW_TITLE>
String
Row title.
Priority Mail Express
<WEBHOOK_TRIGGER_TIMESTAMP>
String
Unix timestamp indicating when the webhook was triggered.
1739321024
<WHATSAPP_BUSINESS_ACCOUNT_ID>
String
WhatsApp Business Account ID.
102290129340398
<WHATSAPP_MESSAGE_ID>
String
WhatsApp message ID.
wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=
<WHATSAPP_USER_ID>
String
WhatsApp user ID. Note that a WhatsApp user’s ID and phone number may not always match.
16505551234
<WHATSAPP_USER_PHONE_NUMBER>
String
WhatsApp user phone number. This is the same value returned by the API as the input value when sending a message to a WhatsApp user. Note that a WhatsApp user’s phone number and ID may not always match.
16505551234
<WHATSAPP_USER_PROFILE_NAME>
String
WhatsApp user’s name as it appears in their profile in the WhatsApp client.
Sheena Nelson

Examples

This example webhook describes a WhatsApp user selecting a row in an interactive list message.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson"
                },
                "wa_id": "16505551234"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "15550783881",
                  "id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA="
                },
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "timestamp": "1749854575",
                "type": "interactive",
                "interactive": {
                  "type": "list_reply",
                  "list_reply": {
                    "id": "priority_express",
                    "title": "Priority Mail Express",
                    "description": "Next Day to 2 Days"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
This example webhook describes a WhatsApp user tapping a button in an interactive reply button message.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson"
                },
                "wa_id": "16505551234"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "15550783881",
                  "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3MEM2RUJFNkI0RENGQTVDRjUA"
                },
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTZBQzg0MzQ4QjRCM0NGNkVGOAA=",
                "timestamp": "1750025136",
                "type": "interactive",
                "interactive": {
                  "type": "button_reply",
                  "button_reply": {
                    "id": "cancel-button",
                    "title": "Cancel"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
This example webhook describes a WhatsApp user sending a single-product message from a business’s catalog.
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson"
                },
                "wa_id": "16505551234"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTZBQzg0MzQ4QjRCM0NGNkVGOAA=",
                "timestamp": "1750025136",
                "type": "interactive",
                "interactive": {
                  "type": "product",
                  "product": {
                    "retailer_id": "2lc20305pt",
                    "title": "Classic T-Shirt",
                    "description": "100% cotton, unisex fit",
                    "currency_code": "USD",
                    "price_amount": 1000,
                    "sale_price_amount": 800,
                    "url": "https://example.com/products/classic-t-shirt"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}