Contacts 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 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.

Syntax

Many contact properties may be omitted if the WhatsApp user chooses not to share them or if their device prevents sharing.

{  
  "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": "contacts",  
                "contacts": [  
                  {  
                    "addresses": [  
                      {  
                        "city": "<CONTACT_CITY>",  
                        "country": "<CONTACT_COUNTRY>",  
                        "country_code": "<CONTACT_COUNTRY_CODE>",  
                        "state": "<CONTACT_STATE>",  
                        "street": "<CONTACT_STREET>",  
                        "type": "<CONTACT_ADDRESS_TYPE>",  
                        "zip": "<CONTACT_ZIP>"  
                      }  
                    ],  
                    "birthday": "<CONTACT_BIRTHDAY>",  
                    "emails": [  
                      {  
                        "email": "<CONTACT_EMAIL>",  
                        "type": "<CONTACT_EMAIL_TYPE>"  
                      }  
                    ],  
                    "name": {  
                      "formatted_name": "<CONTACT_FORMATTED_NAME>",  
                      "first_name": "<CONTACT_FIRST_NAME>",  
                      "last_name": "<CONTACT_LAST_NAME>",  
                      "middle_name": "<CONTACT_MIDDLE_NAME>",  
                      "suffix": "<CONTACT_NAME_SUFFIX>",  
                      "prefix": "<CONTACT_NAME_PREFIX>"  
                    },  
                    "org": {  
                      "company": "<CONTACT_ORG_COMPANY>",  
                      "department": "<CONTACT_ORG_DEPARTMENT>",  
                      "title": "<CONTACT_ORG_TITLE>"  
                    },  
                    "phones": [  
                      {  
                        "phone": "<CONTACT_PHONE>",  
                        "wa_id": "<CONTACT_WHATSAPP_PHONE_NUMBER>",  
                        "type": "<CONTACT_PHONE_TYPE>"  
                      }  
                    ],  
                    "urls": [  
                      {  
                        "url": "<CONTACT_URL>",  
                        "type": "<CONTACT_URL_TYPE>"  
                      }  
                    ]  
                  }  
                ],  
  
                <!-- 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
<CONTACT_ADDRESS_TYPE> String	The type of address, such as home or work.	Home
<CONTACT_BIRTHDAY> String	The contact's 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.	bjohson@socialtsunami.com
<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, or work.	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, or Instagram.	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

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": "contacts",  
                "contacts": [  
                  {  
                    "name": {  
                      "first_name": "Barbara",  
                      "last_name": "Johnson",  
                      "formatted_name": "Barbara J. Johnson"  
                    },  
                    "org": {  
                      "company": "Social Tsunami"  
                    },  
                    "phones": [  
                      {  
                        "phone": "+1 (415) 555-0829",  
                        "wa_id": "14125550829",  
                        "type": "MOBILE"  
                      }  
                    ]  
                  }  
                ]  
              }  
            ]  
          },  
          "field": "messages"  
        }  
      ]  
    }  
  ]  
}