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
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": [
{
"from": "<WHATSAPP_USER_PHONE_NUMBER>",
"id": "<WHATSAPP_MESSAGE_ID>",
"timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
"type": "text",
"text": {
"body": "<MESSAGE_TEXT_BODY>"
},
<!-- only if message originated from a "Message business" button -->
"context": {
"from": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
"id": "<CONTEXTUAL_WHATSAPP_MESSAGE_ID>",
"referred_product": {
"catalog_id": "<PRODUCT_CATALOG_ID>",
"product_retailer_id": "<PRODUCT_ID>"
}
},
<!-- only if message forwarded to business by a user -->
"context": {
"forwarded": true, <!-- only included if forwarded 5 times or less -->
"frequently_forwarded": true <!-- only included if forwarded more than 5 times -->
},
<!-- only included if message sent via a Click to WhatsApp ad -->
"referral": {
"source_url": "<AD_URL>",
"source_id": "<AD_ID>",
"source_type": "ad",
"body": "<AD_PRIMARY_TEXT>",
"headline": "<AD_HEADLINE>",
"media_type": "<AD_MEDIA_TYPE>",
"image_url": "<AD_IMAGE_URL>",
"video_url": "<AD_VIDEO_URL>",
"thumbnail_url": "<AD_VIDEO_THUMBNAIL>",
"ctwa_clid": "<AD_CLICK_ID>", <!-- omitted if message sent via a WhatsApp Status ad placement -->
"welcome_message": {
"text": "<AD_GREETING_TEXT>"
}
}
}
]
},
"field": "messages"
}
]
}
]
}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). | |
<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 | 194836987003835 | |
<PRODUCT_ID>String | 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 |
Examples
Text message
This example describes a text message sent by a WhatsApp user (the user just typed something into the chat field and sends).
{
"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.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
"timestamp": "1749416383",
"type": "text",
"text": {
"body": "Does it come in another color?"
}
}
]
},
"field": "messages"
}
]
}
]
}Message business button
This example describes a text message sent by a WhatsApp user who used a Message business button when viewing a single product to send the message.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "419561257915477",
"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.HBgLMTY1MDM4Nzk0MzkVAgARGA9wcm9kdWN0X2lucXVpcnkA",
"referred_product": {
"catalog_id": "194836987003835",
"product_retailer_id": "di9ozbzfi4"
}
},
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTA2NTUwRkNEMDdFQjJCRUU0NQA=",
"timestamp": "1750016800",
"text": {
"body": "Is this still available?"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Click to WhatsApp ad
This example describes a text message sent by a WhatsApp user who tapped a Click to WhatsApp ad and sent the generated message to the business.
Note that for messages originating from an ad in WhatsApp Status (WhatsApp Status ad placements) the
referral.ctwa_clid property is omitted entirely.{
"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": [
{
"referral": {
"source_url": "https://fb.me/3cr4Wqqkv",
"source_id": "120226305854810726",
"source_type": "ad",
"body": "Summer Succulents are here!",
"headline": "Chat with us",
"media_type": "image",
"image_url": "https://scontent.xx.fbcdn.net/v/t45.1...",
"ctwa_clid": "Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4_0NiNhEgpGo0AHemvuSoifXaytfTzcchptiErTKCqTrJ5nW1h7IHYeYymGb5K5J5iTROpBhWAGaIAeUzHL50",
"welcome_message": {
"text": "Hi there! Let us know how we can help!"
}
},
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUQ0N0VFMDA2MTQ0RkJFNkNDNAA=",
"timestamp": "1750275992",
"text": {
"body": "Can I get more info about this?"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}
No comments to display
No comments to display