> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/partner/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/partner/messaging/sending-and-receiving-messages/text-messages/contacts-and-location-messages.md).

# Contacts & Location Messages

{% hint style="info" %}
You can only send a location message up until 24 hours after receiving a message from the user. If you have not received a message from the user within this time, you will need to start a new conversation by [sending a Template message](/partner/messaging/template-messages/sending-template-messages.md)[.](/partner/messaging/template-messages/sending-template-messages.md)
{% endhint %}

## How to send Location Messages

To send location messages, use this [endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/messages#post-messages) and attach a `message` object with `type=location`. Then, add a[ location object. ](#location-object)

#### Request Body

| Name                                                 | Type   | Description                                                                                                                   |
| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| to<mark style="color:red;">\*</mark>                 | string | Recipient wa\_id                                                                                                              |
| type<mark style="color:red;">\*</mark>               | string | Message type: `location`                                                                                                      |
| location<mark style="color:red;">\*</mark>           | object | See [Location Object](#location-object).                                                                                      |
| messaging\_product<mark style="color:red;">\*</mark> | string | <p><strong>Required  only for Cloud API.</strong><br>Messaging service used for the request. Use <code>"whatsapp"</code>.</p> |

```json
POST https://waba-v2.360dialog.io/messages' \
 
 {
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": LONG_NUMBER,
    "latitude": LAT_NUMBER,
    "name": LOCATION_NAME,
    "address": LOCATION_ADDRESS
  }
}'

```

#### Location Object <a href="#location-object" id="location-object"></a>

| Name        | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `longitude` | <p><strong>Required.</strong></p><p>Longitude of the location.</p> |
| `latitude`  | <p><strong>Required.</strong></p><p>Latitude of the location.</p>  |
| `name`      | <p><strong>Required.</strong></p><p>Name of the location.</p>      |
| `address`   | <p><strong>Required.</strong></p><p>Address of the location.</p>   |

The location message will look like this to the end user:

<figure><img src="/files/7G3MfWEKnvGZXk3p3rMv" alt="" width="375"><figcaption></figcaption></figure>

## How to send Contacts Messages

To send contact messages, muse this[ endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/messages#post-messages) and attach a `message` object with `type=contacts`. Then, add a [contacts object. ](#contacts-object)

#### Request Body

<table><thead><tr><th>Name</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>to<mark style="color:red;">*</mark></td><td>string</td><td>Recipient wa_id</td></tr><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Message type: <code>contacts</code></td></tr><tr><td>messaging_product<mark style="color:red;">*</mark></td><td>string</td><td><strong>Required  for Cloud API.</strong><br>Use <code>"whatsapp"</code>.</td></tr><tr><td>contacts<mark style="color:red;">*</mark></td><td>object</td><td>See <a href="#contacts-object">Contacts Object.</a></td></tr></tbody></table>

```json
POST https://waba-v2.360dialog.io/messages' \

 {
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "contacts",
  "contacts": [{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
    }]
}
```

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

Inside `contacts`, you can nest the following objects: `addresses`, `emails`, `name`, `org`, `phone`, and `urls`. **Pluralized objects are to 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"
        }]
    }
]
```

The contact message will look like this to the end user:

<figure><img src="/files/rW7Axi5kkAfCPbme6sye" alt="" width="375"><figcaption></figcaption></figure>

###

## How to block 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 %}

Use this [endpoint](/partner/partner-api/api-reference/channel-management.md#post-api-v2-partners-partner_id-channels-channel_id-block_users) to block a list of WhatsApp user numbers. As an authentication, please use the partner API Key. How to create it can be found [here](https://docs.360dialog.com/partner/integrations-and-api-development/integration-best-practices/api-key-authentication-for-the-partner-api#how-to-create-view-and-delete-api-keys).&#x20;

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

Use this [endpoint](/partner/partner-api/api-reference/channel-management.md#delete-api-v2-partners-partner_id-channels-channel_id-block_users) to unblock a list of WhatsApp user numbers.

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

Use this [endpoint](/partner/partner-api/api-reference/channel-management.md#get-api-v2-partners-partner_id-channels-channel_id-block_users) to get a list of blocked numbers on a specific WhatsApp Business number.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.360dialog.com/partner/messaging/sending-and-receiving-messages/text-messages/contacts-and-location-messages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.