Interactive messages webhook reference

Updated: May 21, 2026

This reference describes trigger events and payload contents for the WhatsApp Business account messages webhook for replies to interactive messages.

Triggers

• A WhatsApp user taps a row in an interactive list message.
• A WhatsApp user taps a button in an interactive reply button message.

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>"  
                  }  
                }  
              }  
            ]  
          },  
          "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=
<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"  
        }  
      ]  
    }  
  ]  
}