Video messages webhook reference

Updated: Jun 17, 2026

This reference describes trigger events and payload contents for the WhatsApp Business account messages webhook for messages containing a video.

Triggers

• A WhatsApp user sends a video to a business.
• A WhatsApp user forwards a video to a business.
• A WhatsApp user sends a video to a business via a Click to WhatsApp ad.

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⁠).	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
<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 video message webhook

{  
  "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"  
        }  
      ]  
    }  
  ]  
}