Video messages webhook reference | Developer Documentation
Video messages webhook reference
Updated: Dec 11, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing a video.
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": "video",
"video": {
"caption": "<MEDIA_ASSET_CAPTION>",
"mime_type": "<MEDIA_ASSET_MIME_TYPE>",
"sha256": "<MEDIA_ASSET_SHA256_HASH>",
"id": "<MEDIA_ASSET_ID>",
"url": "<MEDIA_ASSET_URL>"
},
<!-- only included if message was forwarded to business by a user -->
"context": {
"forwarded": true <!-- only if forwarded 5 times or less -->
"frequently_forwarded": true <!-- only 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>",
"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 |
<IDENTITY_KEY_HASH>String | Identity key hash. Only included if you have enabled the identity change check feature. | DF2lS5v2W6x= |
<MEDIA_ASSET_CAPTION>String | Media asset caption text. | Taj Mahal |
<MEDIA_ASSET_ID>String | Media asset ID. You can perform a GET on this ID to get the asset URL, then perform a GET on the returned URL (using your access token) to get the underlying asset. | 1003383421387256 |
<MEDIA_ASSET_MIME_TYPE>String | Media asset MIME type. | image/jpeg |
<MEDIA_ASSET_SHA256_HASH>String | Media asset SHA-256 hash. | SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI= |
<MEDIA_ASSET_URL>String | This JSON property is being released to developers gradually over several weeks, starting November 12, 2025, and may not be available to you immediately. Media URL. You can query this URL directly with your access token to download the media asset. | https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133... |
<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": [
{
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
"timestamp": "1744344496",
"type": "video",
"video": {
"caption": "Timelapse of growth",
"mime_type": "video/mp4",
"sha256": "vdGU5X4caz12KwFgYwpljlUNqMt1YnkH+5GkPc3mMnc=",
"id": "731675419373506",
"url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
}
}
]
},
"field": "messages"
}
]
}
]
}
No comments to display
No comments to display