Contacts

This page describes contacts messages on the WhatsApp Business Platform.

Contact messages enable the sharing of structured contact information directly with WhatsApp users, including 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.

Contact Message Request

Use the messages endpoint to send a contacts message to a WhatsApp user.

POST https://waba-v2.360dialog.io/messages

Headers

Name	Value
Content-Type	application/json
Authorization	D360-API-KEY

Body Example

{
  "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 -->
      ]
    }
  ]
}

Response

200

{
  "contacts": [
    {
      "input": "text",
      "wa_id": "text"
    }
  ],
  "messages": [
    {
      "id": "text",
      "message_status": "accepted"
    }
  ],
  "messaging_product": "text"
}

400

Contacts Object

Inside contacts, the following objects can be nested: addresses, emails, name, org, phone, and urls. Plural objects should be wrapped in an array, as shown in the example below.

Name	Description
addresses object	Optional. Full contact address(es) formatted as an addresses object. The object can contain the following fields: streetstring – Optional. Street number and name. citystring – Optional. City name. statestring – Optional. State abbreviation. zipstring – Optional. ZIP code. countrystring – Optional. Full country name. country_codestring – Optional. Two-letter country abbreviation. typestring – Optional. Standard values are HOME and WORK.
birthday	Optional. YYYY-MM-DD formatted string.
emails object	Optional. Contact email address(es) formatted as an emails object. The object can contain the following fields: emailstring – Optional. Email address. typestring – Optional. Standard values are HOME and WORK.
name object	Required. Full contact name formatted as a name object. The object can contain the following fields: formatted_namestring – Required. Full name, as it normally appears. first_namestring – Optional*. First name. last_namestring – Optional*. Last name. middle_namestring – Optional*. Middle name. suffixstring – Optional*. Name suffix. prefixstring – Optional*. Name prefix. *At least one of the optional parameters needs to be included along with the formatted_name parameter.
org object	Optional. Contact organization information formatted as an org object. The object can contain the following fields: companystring – Optional. Name of the contact's company. departmentstring – Optional. Name of the contact's department. titlestring – Optional. Contact's business title.
phones object	Optional. Contact phone number(s) formatted as a phone object. The object can contain the following fields: phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number. typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. wa_idstring – Optional. WhatsApp ID.
urls object	Optional. Contact URL(s) formatted as a urls object. The object can contain the following fields: urlstring – Optional. URL. typestring – Optional. Standard values are HOME and WORK.

Example of a contacts object with pluralized objects nested inside:

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

Blocking Contacts

The Block Users API enables businesses block bad numbers from contacting the account.

When a WhatsApp user is blocked, the following happens:

• The user cannot contact the business or see that they are online.

• The business cannot message the user. If so, an error will occur.

Errors on the API occur per-number, since blocks might be successful on some numbers and not others. The Block Users API is synchronous.

To block a contact, you must have received a message from them within the last 24 hours.

Block Users

POST /block_users

Use this endpoint to block WhatsApp user(s) by phone number or WhatsApp ID.

Headers

Name	Value
Content-Type	application/json
Authorization	D360-API-KEY

Body

Name	Type	Description
messaging_product	string	Must be set to "whatsapp"
block_users	object	List of user(s) to block. Each object contains a user string field (see row below)
user	string	The phone number or WhatsApp ID to be blocked

Request Example

curl --location 'https://waba-v2.360dialog.io/block_users' \
--header 'D360-API-KEY: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messaging_product": "whatsapp",
    "block_users": [
        {
            "user": "PHONE_NUMBER_OR_WHATSAPP_ID"
        }
    ]
}'

Response

200

{
    "messaging_product": "whatsapp",
    "block_users": {
        "added_users": [
            {
                "input": "string",
                "wa_id": "string"
            }
        ]
    }
}

400

Unblock Users

Use this endpoint to unblock a list of WhatsApp user(s).

DELETE /block_users

Headers

Name	Value
Content-Type	application/json
Authorization	D360-API-KEY

Body

Name	Type	Description
messaging_product	string	Must be set to "whatsapp"
block_users	object	List of user(s) to unblock. Each element contains a user field (see row below)
user	string	The phone number or WhatsApp ID to be unblocked

Request Example

curl --location --request DELETE 'https://waba-v2.360dialog.io/block_users' \
--header 'D360-API-KEY: INSERT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messaging_product": "whatsapp",
    "block_users": [
        {
            "user": "PHONE_NUMBER_OR_WHATSAPP_ID"
        }
    ]
}'

Response

200

{
    "messaging_product": "whatsapp",
    "block_users": {
        "removed_users": [
            {
                "input": "string",
                "wa_id": "string"
            }
        ]
    }
}

400

404

List Blocked Users

Use this endpoint to get the list of blocked WhatsApp user(s).

GET /block_users

Headers

Name	Value
Content-Type	application/json
Authorization	D360-API-KEY

Request Example

curl --location 'https://waba-v2.360dialog.io/block_users' \
--header 'D360-API-KEY: INSERT_API_KEY\'

Response

200

{
    "data": [
        {
            "messaging_product": "whatsapp",
            "wa_id": "string"
        }
    ],
    "paging": {
        "cursors": {
            "before": "string",
            "after": "string"
        }
    }
}

400