Contacts and Location Messages
See how to use the message node to send contacts or location messages and how to report and block contacts.
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
to*
string
Recipient wa_id
type*
string
Message type: location
messaging_product*
string
Required only for Cloud API.
Messaging service used for the request. Use "whatsapp"
.
Location Object
longitude
Required.
Longitude of the location.
latitude
Required.
Latitude of the location.
name
Required.
Name of the location.
address
Required.
Address of the location.
The location message will look like this to the end user:
[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.
POST
https://waba.360dialog.io/v1/messages
Request Body
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
to*
string
Recipient wa_id
type*
string
Message type: contacts
messaging_product*
string
Required for Cloud API.
Use "whatsapp"
.
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.
addresses
object
Optional.
Full contact address(es) formatted as an addresses
object.
The object can contain the following fields:
street
string – Optional. Street number and name.
city
string – Optional. City name.
state
string – Optional. State abbreviation.
zip
string – Optional. ZIP code.
country
string – Optional. Full country name.
country_code
string – Optional. Two-letter country abbreviation.
type
string – 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:
email
string – Optional. Email address.
type
string – 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_name
string – Required. Full name, as it normally appears.
first_name
string – Optional*. First name.
last_name
string – Optional*. Last name.
middle_name
string – Optional*. Middle name.
suffix
string – Optional*. Name suffix.
prefix
string – 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:
company
string – Optional. Name of the contact's company.
department
string – Optional. Name of the contact's department.
title
string – Optional. Contact's business title.
phones
object
Optional.
Contact phone number(s) formatted as a phone
object.
The object can contain the following fields:
phone
string – Optional. Automatically populated with the `wa_id` value as a formatted phone number.
type
string – Optional. Standard Values are CELL
, MAIN
, IPHONE
, HOME
, and WORK
.
wa_id
string – Optional. WhatsApp ID.
urls
object
Optional.
Contact URL(s) formatted as a urls
object.
The object can contain the following fields:
url
string – Optional. URL.
type
string – Optional. Standard values are HOME
and WORK
.
Example of a contacts
object with pluralized objects nested inside:
The contact message will look like this to the end user:
[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.
POST
https://waba.360dialog.io/v1/messages
Request Body
How to block 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.
Cloud API: Block Users
Use this endpoint to block a list of WhatsApp user numbers.
POST
https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users
Path Parameters
partner_id
The ID of the Partner.
Example: examplePA
channel_id
The ID of the channel.
Example:exampleCH
Body Parameters
block_users
str array[object]
List of user(s) to block.
Each element contains a user
field.
user
string
The phone number or WhatsApp ID to be blocked.
Example Request
Response
Unblock Users
Use this endpoint to unblock a list of WhatsApp user numbers.
DELETE
https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users
Path Parameters
partner_id
The ID of the Partner.
Example: examplePA
channel_id
The ID of the channel.
Example:exampleCH
Body Parameters
block_users
str array[object]
List of user(s) to unblock.
Each element contains a user
field.
user
string
The phone number or WhatsApp ID to be unblocked.
Example Request
Response
Get List of Blocked Users
Use this endpoint to get a list of blocked numbers on a specific WhatsApp Business number.
GET
https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users
Path Parameters
partner_id
The ID of the Partner.
Example: examplePA
channel_id
The ID of the channel.
Example:exampleCH
Example Request
Response
[will be deprecated] On-premise API: Block Users
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.
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.
When successful, the response will have HTTP status 200
and will come without the "errors" object. The failed response looks like this:
blocking parameters
blocking parameters
The following parameters are supported by POST calls to /v1/contacts/{phone_number}/block
:
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.
Unblock Users
To unblock a contact, send an API call to/v1/contacts/{phone_number}/unblock
When successful, the response will have HTTP status 200
and will come without the "errors" object.
The failed response looks like this:
unblock parameters
unblock parameters
The following parameters are supported by POST calls to /v1/contacts/{phone_number}/unblock
:
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.
Get List of Blocked Users
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.
You will receive a response with a page from your block list and paging information.
block list parameters
block list parameters
The following parameters are supported for GET calls to /v1/contacts/blocklist
:
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.
When successful, the response will have HTTP status 200
and will come without the "errors" object.
The failed response looks like this:
reporting parameters
reporting parameters
The following parameters are supported by POST calls to /v1/contacts/{phone_number}/report
:
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.
Last updated
Was this helpful?