# Contacts

Contact messages enable the sharing of structured contact information directly with WhatsApp users, including names, phone numbers, physical addresses, and email addresses.

![](https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4sMxKjL6eJRvZn6jeG-887967055%2Fuploads%2FQWKT8JDA102pLLkrFF0R%2Fcontact_message.png?alt=media\&token=3f511947-f248-44d4-8e5a-51fd5a37d94a)

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⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Ffaq.whatsapp.com%2F378279804439436%2F%3Fcms_platform%3Dandroid\&h=AT4H6CDyhQ1vPXHIT9nhkgHb5i-CLACYd6cf2Fe1t0FY_r7k30bXHvVXPo9CR5WMxSuQqO9R1DMHGUNDhnht4ctMS0ikTq4F-KtCqVnDUnvEVeaMwehkC-idiTR9haurKdS726eW4UXW-L7yP7z_Hg) for the definitions of primary and linked devices.

### Contact Message Request

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

<mark style="color:orange;">`POST`</mark> `https://waba-v2.360dialog.io/messages`

**Headers**

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

**Body Example**

```json
{
  "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**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

### Contacts Object <a href="#contacts-object" id="contacts-object"></a>

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.

<table><thead><tr><th width="221">Name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>addresses</code></p><p><em>object</em></p></td><td><p><strong>Optional.</strong></p><p>Full contact address(es) formatted as an <code>addresses</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>street</code><em>string</em> – Optional. Street number and name.</p><p><code>city</code><em>string</em> – Optional. City name.</p><p><code>state</code><em>string</em> – Optional. State abbreviation.</p><p><code>zip</code><em>string</em> – Optional. ZIP code.</p><p><code>country</code><em>string</em> – Optional. Full country name.</p><p><code>country_code</code><em>string</em> – Optional. Two-letter country abbreviation.</p><p><code>type</code><em>string</em> – Optional. Standard values are <code>HOME</code> and <code>WORK</code>.</p></td></tr><tr><td><code>birthday</code></td><td><p><strong>Optional.</strong></p><p><code>YYYY-MM-DD</code> formatted string.</p></td></tr><tr><td><p><code>emails</code></p><p><em>object</em></p></td><td><p><strong>Optional.</strong></p><p>Contact email address(es) formatted as an <code>emails</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>email</code><em>string</em> – Optional. Email address.</p><p><code>type</code><em>string</em> – Optional. Standard values are <code>HOME</code> and <code>WORK</code>.</p></td></tr><tr><td><p><code>name</code></p><p><em>object</em></p></td><td><p><strong>Required.</strong></p><p>Full contact name formatted as a <code>name</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>formatted_name</code><em>string</em> – Required. Full name, as it normally appears.</p><p><code>first_name</code><em>string</em> – Optional*. First name.</p><p><code>last_name</code><em>string</em> – Optional*. Last name.</p><p><code>middle_name</code><em>string</em> – Optional*. Middle name.</p><p><code>suffix</code><em>string</em> – Optional*. Name suffix.</p><p><code>prefix</code><em>string</em> – Optional*. Name prefix.</p><p></p><p>*At least one of the optional parameters needs to be included along with the <code>formatted_name</code> parameter.</p></td></tr><tr><td><p><code>org</code></p><p><em>object</em></p></td><td><p><strong>Optional.</strong></p><p>Contact organization information formatted as an <code>org</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>company</code><em>string</em> – Optional. Name of the contact's company.</p><p><code>department</code><em>string</em> – Optional. Name of the contact's department.</p><p><code>title</code><em>string</em> – Optional. Contact's business title.</p></td></tr><tr><td><p><code>phones</code></p><p><em>object</em></p></td><td><p><strong>Optional.</strong></p><p>Contact phone number(s) formatted as a <code>phone</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>phone</code><em>string</em> – Optional. Automatically populated with the `wa_id` value as a formatted phone number.</p><p><code>type</code><em>string</em> – Optional. Standard Values are <code>CELL</code>, <code>MAIN</code>, <code>IPHONE</code>, <code>HOME</code>, and <code>WORK</code>.</p><p><code>wa_id</code><em>string</em> – Optional. WhatsApp ID.</p></td></tr><tr><td><p><code>urls</code></p><p><em>object</em></p></td><td><p><strong>Optional.</strong></p><p>Contact URL(s) formatted as a <code>urls</code> object. </p><p></p><p>The object can contain the following fields:</p><p><code>url</code><em>string</em> – Optional. URL.</p><p><code>type</code><em>string</em> – Optional. Standard values are <code>HOME</code> and <code>WORK</code>.</p></td></tr></tbody></table>

Example of a `contacts` object with pluralized objects nested inside:

```json
"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 <a href="#how-to-block-contacts" id="how-to-block-contacts"></a>

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.

{% hint style="warning" %}
To block a contact, you must have received a message from them within the last 24 hours.
{% endhint %}

### Block Users

<mark style="color:green;">`POST`</mark> `/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 | <p>List of user(s) to block.</p><p>Each object contains a <code>user</code> string field (see row below)</p> |
| user               | string | The phone number or WhatsApp ID to be blocked                                                                |

**Request Example**

```shellscript
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**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
    "detail": {
        "<location>": {
            "<field_name>": [
                "string"
            ]
        }
    },
    "message": "string"
}
```

{% endtab %}
{% endtabs %}

### Unblock Users <a href="#block-users-2" id="block-users-2"></a>

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

<mark style="color:red;">`DELETE`</mark> `/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 | <p>List of user(s) to unblock.</p><p>Each element contains a <code>user</code> field (see row below)</p> |
| user               | string | The phone number or WhatsApp ID to be unblocked                                                          |

**Request Example**

```shellscript
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**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
    "detail": {
        "<location>": {
            "<field_name>": [
                "string"
            ]
        }
    },
    "message": "string"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "detail": {},
    "message": "string"
}
```

{% endtab %}
{% endtabs %}

### List Blocked Users <a href="#block-users-2" id="block-users-2"></a>

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

<mark style="color:green;">`GET`</mark> `/block_users`

**Headers**

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

**Request Example**

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

**Response**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
    "detail": {
        "<location>": {
            "<field_name>": [
                "string"
            ]
        }
    },
    "message": "string"
}
```

{% endtab %}
{% endtabs %}