# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/docs/messaging/message-types/contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.