Skip to main content

Contacts messages webhook reference | Developer Documentation

Contacts messages webhook reference

Updated: Oct 22, 2025
This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for messages containing one or more contacts.

Triggers

    A WhatsApp user sends one or more contacts to a business.A WhatsApp user sends one or more contacts to a business via a Click to WhatsApp ad.

    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
    <CONTACT_ADDRESS_TYPE>
    String
    Type of address, such as home or work.
    Home
    <CONTACT_BIRTHDAY>
    String
    Contact birthday.
    1999-01-23
    <CONTACT_CITY>
    String
    City mentioned in the contact address.
    Menlo Park
    <CONTACT_COUNTRY_CODE>
    String
    ISO country code on the contact address.
    US
    <CONTACT_COUNTRY>
    String
    Country mentioned in the contact address.
    United States
    <CONTACT_EMAIL_TYPE>
    String
    Type of email, such as personal or work.
    Personal
    <CONTACT_EMAIL>
    String
    Email address of the contact.
    <CONTACT_FIRST_NAME>
    String
    Contact's first name.
    Barbara
    <CONTACT_FORMATTED_NAME>
    String
    Contact's formatted name.
    Barbara J. Johnson
    <CONTACT_LAST_NAME>
    String
    Contact's last name.
    Johnson
    <CONTACT_MIDDLE_NAME>
    String
    Contact's middle name.
    Joana
    <CONTACT_NAME_PREFIX>
    String
    Contact's name prefix.
    Dr.
    <CONTACT_NAME_SUFFIX>
    String
    Contact's name suffix.
    Esq.
    <CONTACT_ORG_COMPANY>
    String
    Name of the company where the contact works.
    Social Tsunami
    <CONTACT_ORG_DEPARTMENT>
    String
    Name of the department where the contact works.
    Engineering
    <CONTACT_ORG_TITLE>
    String
    Contact's job title.
    Software Engineer
    <CONTACT_PHONE_TYPE>
    String
    Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc.
    CELL
    <CONTACT_PHONE>
    String
    Contact's phone number.
    +14125550829
    <CONTACT_STATE>
    String
    State mentioned in the contact address.
    CA
    <CONTACT_STREET>
    String
    Street mentioned in the contact address.
    1 Hacker Way
    <CONTACT_URL_TYPE>
    String
    Type of website. For example, company, work, personal, Facebook Page, Instagram, etc.
    Company
    <CONTACT_URL>
    String
    Website URL associated with the contact or their company.
    socialtsunami.com
    <CONTACT_WHATSAPP_PHONE_NUMBER>
    String
    Contact's WhatsApp number.
    14125550829
    <CONTACT_ZIP>
    String
    Zip code in the contact address.
    94025
    <IDENTITY_KEY_HASH>
    String
    Identity key hash. Only included if you have enabled the identity change check feature.
    DF2lS5v2W6x=
    <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
    Back to top