Contacts and Location Messages

Use the message node to send contacts or location messages.

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.

Sending Location Messages

To send location messages, make a POST call to the /messages endpoint and attach a message object with type=location. Then, add a location object.

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

Request Body

Name	Type	Description
to*	string	Recipient wa_id
type*	string	Message type: location
location*	object	See Location Object.
messaging_product*	string	Required only for Cloud API. Messaging service used for the request. Use "whatsapp".

200

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

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

Name	Description
longitude	Required. Longitude of the location.
latitude	Required. Latitude of the location.
name	Required. Name of the location.
address	Required. Address of the location.

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.

POST https://waba.360dialog.io/v1/messages

Request Body

Name	Type	Description
type*	string	Message type: location
to*	string	Recipient wa_id
location*	object	See Location Object.

200

For On-premise API, a successful response looks like this:

{
    "messages": [{
       "id": "message-id"
    }]
}

{
    "to": "recipient-wa-id",
    "type": "location",
    "location": {
        "longitude": -122.425332,
        "latitude": 37.758056,
        "name": "Facebook HQ",
        "address": "1 Hacker Way, Menlo Park, CA 94025"
    }
}

Sending Contacts Messages

To send contact messages, make a POST call to the /messages endpoint and attach a message object with type=contacts. Then, add a contacts object.

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

Request Body

Name	Type	Description
to*	string	Recipient wa_id
type*	string	Message type: contacts
messaging_product*	string	Required for Cloud API. Use "whatsapp".
contacts*	object	See Contacts Object.

200

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

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

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.

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

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.

POST https://waba.360dialog.io/v1/messages

Request Body

Name	Type	Description
type*	string	Message type: contacts
to*	string	Recipient wa_id
contacts*	object	See Contacts Object.

200

{
    "messages": [{
       "id": "message-id"
    }]
}

curl --location 'https://waba.360dialog.io/v1/messages' \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: {{API_KEY}}' \
--data '{
    "to": "WA_ID",
    "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"
                }
            ]
        }
    ]
}'

How to block contacts

Currently, it is not possible to block or unblock contacts in the Cloud API. Please refer to Meta's Support regarding this limitation.

If you block a number in On-premise and then migrate to Cloud API, the number will remain blocked without the option to unblock it.

[will be deprecated] If the WABA is registered in On-premise API

Check contacts

Before sending a message to a number, you can check contact availability alongside preloading contact information before sending a message to the number. We recommend the preloading of contact information before sending messages in large volumes, for improved performance.

You can find more information about this process in the official WhatsApp documentation.

Starting in v2.39 and above, you do not have to call the contacts node before sending a message sending a message.

Starting in v2.43, there will be changes to the behavior of the contacts endpoint. Responses for status will change.

Regardless of whether a user has WhatsApp, it will always return valid for status in the response and a wa_id. There is no guarantee that the returned wa_id will be valid. These changes are applicable for both direct responses, as well as webhook responses for non-blocking calls Ensure your code avoids relying on status and wa_id returned in the contacts node.

POST https://waba.360dialog.io/v1/contacts

Send an API call to /v1/contacts containing an array of registered phone numbers. The phone numbers can be in any standard telephone number format.

Request Body

Name	Type	Description
blocking	string	no_wait (default), wait
contacts	array	[phone]
force_check	boolean	false (default), true

200

{
  "contacts": [ {
    "input": "[phone]",
    "wa_id": "55123456789", 
    "status": "valid" <- we can send messages to valid contacts only
  }]
}

Example Request

{
  "blocking": "wait",
  "contacts": [
   "[phone]"
  ],
  "force_check": true
}

Example Response

{
    "contacts": [
        {
            "input": "[phone]",
            "status": "valid",
            "wa_id": "55123456789"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.35.4"
    }
}

The response will contain a wa_id. You may use this or another valid wa_id when sending messages using the below request(s).

How to block contacts

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

Submit an API call to /v1/contacts/{phone_number}/block with a reason for blocking another business account.

POST / v1 / contacts /+ 16315551000 / block
 { "reason" : "Optional string(0;60). Freeform block reason. Will be used when another business account is being blocked" }

When successful, the response will have HTTP status 200and will come without the "errors" object. The failed response looks like this:

{ "errors" : [ { "code" : 2048 , "title" : "Not engaged contact" , "details" : "Invalid Request. This contact has not engaged with you in the last 24 hrs." } ] }   

blocking parameters

The following parameters are supported by POST calls to /v1/contacts/{phone_number}/block:

Settings	Description
reason	Optional. Blocking reason in free text format. It will be used during the process of blocking another business account. Must be less than 60 characters.
phone_number	Mandatory. Numbers can be in any phone number format. The recommended format for contact phone numbers includes a plus sign (+) and country code.

How to unblock contacts

To unblock a contact, send an API call to/v1/contacts/{phone_number}/unblock

POST / v1 / contacts /+ 16315551000 / unblock

When successful, the response will have HTTP status 200and will come without the "errors" object.

The failed response looks like this:

{ "errors" : [ { "code" : 1009 , "title" : "Parameter value is not valid" , "details" : "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code" } ] }   
     

unblock parameters

The following parameters are supported by POST calls to /v1/contacts/{phone_number}/unblock:

Settings	Description
phone_number	Mandatory. Numbers can be in any phone number format. The recommended format for contact phone numbers includes a plus sign (+) and country code.

How to get a Block List

Here's how to get a list of your blocked contacts.

Send an API call to /v1/contacts/blocklist to receive a paginated list of your blocked contacts.

GET / v1 / contacts / blocklist ? limit = 10 & offset = 0

You will receive a response with a page from your block list and paging information.

{ "contacts" : [ { "wa_id" : "[e-mail]" } ], "pagination" : { "limit" : 10 , "offset" : 0 , "total" : 1 } }
    

block list parameters

The following parameters are supported for GET calls to /v1/contacts/blocklist:

Settings	Description
limit	Optional. Accepted range is (0;200]. Default: 100.
offset	Optional. Default: 0.

How to Report a Contact

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

Send an API call to /v1/contacts/{phone_number}/report including a reason if you are blocking another business account.

POST / v1 / contacts /+ 16315551000 / block
 { "reason" : "Optional string(0;60). Freeform block reason. Will be used when another business account is being blocked" , "block" : "true | false optional boolean with default of false" , "message_id" : "message-id. Optional reported message id" }
 

When successful, the response will have HTTP status 200and will come without the "errors" object.

The failed response looks like this:

{ "errors" : [ { "code" : 2048 , "title" : "Not engaged contact" , "details" : "Invalid Request. This contact has not engaged with you in the last 24 hrs." } ] }  

reporting parameters

The following parameters are supported by POST calls to /v1/contacts/{phone_number}/report:

Settings	Description
reason	Optional. Blocking reason in free text format. It will be used during the process of blocking another business account. Must be less than 60 characters.
block	Optional. The default is False. If you just want to report or also block the contact.
message_id	Optional. The ID of the message to be reported. If not specified, the last 5 messages will be sent to WhatsApp.
phone_number	Mandatory. Numbers can be in any phone number format. The recommended format for contact phone numbers includes a plus sign (+) and country code.