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
Syntax
Note that many contact object properties may be omitted if the WhatsApp user chooses not to share them, or their device prevents them from being shared.
{
"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). | |
<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 |
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"
}
]
}
]
}
No comments to display
No comments to display