Button `messages` webhook reference

This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for quick-reply button messages.

Triggers

A WhatsApp user taps a quick-reply button in a template 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": "button",                 "button": {                   "payload": "<BUTTON_LABEL_TEXT>",                   "text": "<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_LABEL_TEXT>` String	Quick-reply button label text.	`Unsubscribe`
`<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=`
`<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`

Example

 {   "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": "1750091045",                 "type": "button",                 "button": {                   "payload": "Unsubscribe",                   "text": "Unsubscribe"                 }               }             ]           },           "field": "messages"         }       ]     }   ] }