Contacts messages | Developer Documentation
Contacts messages
Updated: Nov 3, 2025
Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses.
When a WhatsApp user taps the message’s profile arrow, it displays the contact’s information in a profile view:
Each message can include information for up to 257 contacts, although it is recommended to send fewer for usability and negative feedback reasons.
Please be aware that a contact’s metadata (e.g., addresses, birthdays, emails) may not be supported by the recipient, especially on their primary device. Please refer to this documentation for the definitions of primary and linked devices.
Request syntax
Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages endpoint to send a contacts message to a WhatsApp user.
curl 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
"messaging_product": "whatsapp",
"to": "<WHATSAPP_USER_PHONE_NUMBER>",
"type": "contacts",
"contacts": [
{
"addresses": [
{
"street": "<STREET_NUMBER_AND_NAME>",
"city": "<CITY>",
"state": "<STATE_CODE>",
"zip": "<ZIP_CODE>",
"country": "<COUNTRY_NAME>",
"country_code": "<COUNTRY_CODE>",
"type": "<ADDRESS_TYPE>"
}
<!-- Additional addresses objects go here, if using -->
],
"birthday": "<BIRTHDAY>",
"emails": [
{
"email": "<EMAIL_ADDRESS>",
"type": "<EMAIL_TYPE>"
}
<!-- Additional emails objects go here, if using -->
],
"name": {
"formatted_name": "<FULL_NAME>",
"first_name": "<FIRST_NAME>",
"last_name": "<LAST_NAME>",
"middle_name": "<MIDDLE_NAME>",
"suffix": "<SUFFIX>",
"prefix": "<PREFIX>"
},
"org": {
"company": "<COMPANY_OR_ORG_NAME>",
"department": "<DEPARTMENT_NAME>",
"title": "<JOB_TITLE>"
},
"phones": [
"phone": "<PHONE_NUMBER>",
"type": "<PHONE_NUMBER_TYPE>",
"wa_id": "<WHATSAPP_USER_ID>"
}
<!-- Additional phones objects go here, if using -->
],
"urls": [
{
"url": "<WEBSITE_URL>",
"type": "<WEBSITE_TYPE>"
}
<!-- Additional URLs go here, if using -->
]
}
]
}'Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String | Required. | |
<ADDRESS_TYPE>String | Optional. Type of address, such as home or work. | Home |
<API_VERSION>String | Optional. Graph API version. | v25.0 |
<BIRTHDAY>String | Optional. Contact’s birthday. Must be in YYYY-MM-DD format. | 1999-01-23 |
<CITY>String | Optional. City where the contact resides. | Menlo Park |
<COMPANY_OR_ORG_NAME>String | Optional. Name of the company where the contact works. | Lucky Shrub |
<COUNTRY_CODE>String | Optional. ISO two-letter country code. | US |
<COUNTRY_NAME>String | Optional. Country name. | United States |
<DEPARTMENT_NAME>String | Optional. Department within the company. | Legal |
<EMAIL_ADDRESS>String | Optional. Email address of the contact. | |
<EMAIL_TYPE>String | Optional. Type of email, such as personal or work. | Work |
<FIRST_NAME>String | Optional. Contact’s first name. | Barbara |
<FORMATTED_NAME>String | Required. Contact’s formatted name. This will appear in the message alongside the profile arrow button. | Barbara J. Johnson |
<JOB_TITLE>String | Optional. Contact’s job title. | Lead Counsel |
<LAST_NAME>String | Optional. Contact’s last name. | Johnson |
<MIDDLE_NAME>String | Optional. Contact’s middle name. | Joana |
<PHONE_NUMBER>String | Optional. WhatsApp user phone number. | +16505559999 |
<PHONE_NUMBER_TYPE>String | Optional. Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. | Home |
<PREFIX>String | Optional. Prefix for the contact’s name, such as Mr., Ms., Dr., etc. | Dr. |
<STATE_CODE>String | Optional. Two-letter state code. | CA |
<STREET_NUMBER_AND_NAME>String | Optional. Street address of the contact. | 1 Lucky Shrub Way |
<SUFFIX>String | Optional. Suffix for the contact’s name, if applicable. | Esq. |
<WEBSITE_TYPE>String | Optional. Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. | Company |
<WEBSITE_URL>String | Optional. Website URL associated with the contact or their company. | https://www.luckyshrub.com |
<WHATSAPP_USER_ID>String | Optional. WhatsApp user ID. If omitted, the message will display an Invite to WhatsApp button instead of the standard buttons. See Button Behavior below. | 19175559999 |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String | Required. WhatsApp business phone number ID. | 106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String | Required. WhatsApp user phone number. | +16505551234 |
<ZIP_CODE>String | Optional. Postal or ZIP code. | 94025 |
If you include the contact’s WhatsApp ID in the message (via the
wa_id property), the message will include a Message and a Save contact button:
If the WhatsApp user taps the Message button, it will open a new message with the contact. If the user taps the Save contact button, they will be given the option to save the contact as a new contact, or to update an existing contact.
If you omit the
wa_id property, both buttons will be replaced with an Invite to WhatsApp button:
Example request
Example request to send a contacts message with two physical addresses, two email addresses, two phone numbers, and two website URLs.
curl 'https://graph.facebook.com/v25.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"messaging_product": "whatsapp",
"to": "+16505551234",
"type": "contacts",
"contacts": [
{
"addresses": [
{
"street": "1 Lucky Shrub Way",
"city": "Menlo Park",
"state": "CA",
"zip": "94025",
"country": "United States",
"country_code": "US",
"type": "Office"
},
{
"street": "1 Hacker Way",
"city": "Menlo Park",
"state": "CA",
"zip": "94025",
"country": "United States",
"country_code": "US",
"type": "Pop-Up"
}
],
"birthday": "1999-01-23",
"emails": [
{
"email": "[email protected]",
"type": "Work"
},
{
"email": "[email protected]",
"type": "Work (old)"
}
],
"name": {
"formatted_name": "Barbara J. Johnson",
"first_name": "Barbara",
"last_name": "Johnson",
"middle_name": "Joana",
"suffix": "Esq.",
"prefix": "Dr."
},
"org": {
"company": "Lucky Shrub",
"department": "Legal",
"title": "Lead Counsel"
},
"phones": [
{
"phone": "+16505559999",
"type": "Landline"
},
{
"phone": "+19175559999",
"type": "Mobile",
"wa_id": "19175559999"
}
],
"urls": [
{
"url": "https://www.luckyshrub.com",
"type": "Company"
},
{
"url": "https://www.facebook.com/luckyshrubplants",
"type": "Company (FB)"
}
]
}
]
}'
Example response
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+16505551234",
"wa_id": "16505551234"
}
],
"messages": [
{
"id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
}
]
}
No comments to display
No comments to display