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.

Triggers

A 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-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50`
`<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`