Text messages webhook reference | Developer Documentation

Text messages webhook reference
Updated: Oct 27, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing only text.
TriggersA WhatsApp user sends a text message to a WhatsApp business phone number.A WhatsApp user forwards a text message to a business phone number.A WhatsApp user uses the Message business button in a catalog, single-, or multi-product message to send a message to the business.A WhatsApp user sends a text message to a business via a Click to WhatsApp ad? (an ad with a WhatsApp message destination). 
Parameters
Placeholder 
Description 
Example value 
<AD_CLICK_ID>
String
Click to WhatsApp ad click ID.
The 
ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements?).
Aff-n8ZTODiE79d22KtA...aIAeUzHL50
<AD_GREETING_TEXT>
String
Click to WhatsApp ad greeting text.
Hi there! Let us know how we can help!
<AD_HEADLINE>
String
Click to WhatsApp ad headline.
Chat with us
<AD_ID>
String
Click to WhatsApp ad ID.
120226305854810726
<AD_IMAGE_URL>
String
Click to WhatsApp ad image URL. Only included if the ad is an image ad.
https://scontent.xx.fbcdn.net/v/t45.1...
<AD_MEDIA_TYPE>
String
Click to WhatsApp ad media type. Values can be:
image - Indicates an image ad.
video - Indicates a video ad.
image
<AD_PRIMARY_TEXT>
String
Click to WhatsApp ad primary text.
Summer succulents are here!
<AD_URL>
String
Click to WhatsApp ad URL.
https://fb.me/3cr4Wqqkv
<AD_VIDEO_THUMBNAIL>
String
Click to WhatsApp ad video thumbnail URL. Only included if ad is a video ad.
https://scontent.xx.fbcdn.net/v/t45.3...
<AD_VIDEO_URL>
String
Click to WhatsApp ad video URL. Only included if ad is a video ad.
https://scontent.xx.fbcdn.net/v/t45.2...
<BUSINESS_DISPLAY_PHONE_NUMBER>
String
Business display phone number.
15550783881
<BUSINESS_PHONE_NUMBER_ID>
String
Business phone number ID.
106540352242922
<CONTEXTUAL_WHATSAPP_MESSAGE_ID>
String
WhatsApp message ID of the message the WhatsApp user used to access the Message business button.
wamid.HBgLMTY1MDM4Nzk0MzkVAgARGA9wcm9kdWN0X2lucXVpcnkA
<IDENTITY_KEY_HASH>
String
Identity key hash. Only included if you have enabled the identity change check feature.
DF2lS5v2W6x=
<MESSAGE_TEXT_BODY>
String
Text body of the message.
Is it available in another color?
<PRODUCT_CATALOG_ID>
String
Product catalog ID.
194836987003835
<PRODUCT_ID>
String
Product ID.
di9ozbzfi4
<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