Skip to main content

Image messages webhook reference | Developer Documentation

Image 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 an image.

Triggers

    A WhatsApp user sends an image to a business.A WhatsApp user forwards an image message to a business.A WhatsApp user forwards an interactive reply button message to a business.A WhatsApp user sends an image 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": "image",
                    "image": {
                      "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

    {
      "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": "image",
                    "image": {
                      "caption": "Taj Mahal",
                      "mime_type": "image/jpeg",
                      "sha256": "SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=",
                      "id": "1003383421387256",
                      "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
                    }
                  }
                ]
              },
              "field": "messages"
            }
          ]
        }
      ]
    }