LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
      • (temp title) Getting started as a partner
    • Pricing & Billing
      • Payment Methods for BR: Pix & Boleto
      • Month Closing Invoice (MCI)
    • Get API Access
    • Tech Provider Program
      • Understanding the Meta Tech Provider Program
      • Becoming a Meta Tech Provider: A Step-by-Step Guide
  • MM Lite Beta Program
    • Onboarding
    • Sending Messages
    • Expected Errors & Programming Languages
    • MM Lite Sandbox Testing
      • Sending Messages using MM Lite Sandbox
      • Expected Erros & Programming Languages
  • Partner & Account Management
    • Solutions for Partners
      • Benefits for Partners
      • Partner Hub
      • WABA Management
    • Account Setup & Management
      • Prerequisites and best practices for account creation
      • Account Structure
      • Account Creation
  • Integrations & API Development
    • Webhook Events & Setup
      • Webhook Events (Partner & Messaging API)
      • Webhook Configuration & Management
    • Integration Best Practices
      • Architecture and Security
      • Best Practices for Designing Integrations
        • Design a Stable Webhook Receiving Endpoint
      • Sizing Your Environment Based on Expected Throughput
      • Design a Resilient Message Sending Service
      • Integrated Onboarding
        • Basic Integrated Onboarding
        • Custom Integrated Onboarding
        • Host Your Own Embedded Signup
      • API Key Authentication for the Partner API
  • API Reference
    • Messaging API
    • Messaging Health Status
    • Sandbox (Test API Key)
    • Differences Between Cloud API and On-Premise API for Partners
      • [will be deprecated] Messaging with On-Premise API
    • Partner API
  • WABA Management
    • Managing WABA Accounts
      • Using the Partner Hub to manage Clients and Channels
      • Using the Partner API to manage Clients and Channels
      • Partner Permission to Generate API Key
      • Checking Usage & Statistics
    • Phone Number & Hosting
      • Migrating a Phone Number
        • Migrate number from Meta or alternate BSP to 360Dialog
        • Migrate a phone number to a new WABA
        • Migrate a phone number to a new WABA to change messaging Currency
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
      • Hosting type Change (On-premise API to Cloud API)
    • WABA Profile & Compliance
      • Display Name Guidelines
      • WABA Profile Info
      • WABA Policy Enforcement
      • Business Account Verification
    • Partner change (between 360Dialog Partners)
    • WhatsApp Flows
    • Accelerated Onboarding
    • Business Account Verification
  • Messaging
    • Sending & Receiving Messages
      • Conversations
      • Receiving messages
      • Before sending a message
    • Message Types
      • Conversational Components
      • Checklist for Message Broadcasts and Campaigns
      • Text messages
      • Interactive messages
        • Single and Multi Product Messages
        • Location Request Messages
        • Address Messages (India and Singapore only)
      • Contacts & Location Messages
    • Template Messages
      • Template Library
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Media Messages
      • Upload, retrieve or delete media
    • Messaging Health & Troubleshooting
      • Messaging Limits & Quality Rating
      • Errors While Messaging
      • Messages statuses
  • Commerce & Payments
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore Only)
      • Receive WhatsApp Payments via Stripe
    • Products and Catalogs
      • India Businesses: Compliance for Commerce
  • Support & Updates
    • Help & Troubleshooting
      • FAQ
      • Error Code Reference
      • User Support Documentation
        • Tutorials
          • Page How to Troubleshoot Login Issues in the 360dialog Hub
          • How to Report an Issue
          • How to Contact Support
        • How-To Guides
          • Raise a support request
          • Requesting a Status Update for Business Verification
        • Reference
          • Troubleshooting Embedded Signup Issues
          • Commerce Policy Checks for WhatsApp API Access
          • Support Availability & SLAs
          • Incident Issue Prioritization
          • Case Types Table
        • Explanation
          • Why Business Verification Takes Time
          • Why Some Issues Are Not Emergencies
          • Understanding the Support Process
      • Support with Meta
    • Imprint & Data Privacy
    • Product Updates & News
      • How to ensure your Template Messages will be received
      • Integrated Onboarding new look and Campaigns Best Practices
Powered by GitBook
On this page
  • Sending Location Messages
  • [will be deprecated] If the WABA is registered in On-premise API
  • Sending Contacts Messages
  • [will be deprecated] If the WABA is registered in On-premise API
  • How to block contacts
  • Cloud API: Block Users
  • Unblock Users
  • Get List of Blocked Users
  • [will be deprecated] On-premise API: Block Users
  • Unblock Users
  • Get List of Blocked Users
  • How to Report a Contact

Was this helpful?

  1. Messaging
  2. Message Types

Contacts & Location Messages

See how to use the message node to send contacts or location messages and how to report and block contacts.

PreviousAddress Messages (India and Singapore only)NextTemplate Messages

Last updated 2 months ago

Was this helpful?

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 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

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

Request Body

Name
Type
Description

to*

string

Recipient wa_id

type*

string

Message type: location

location*

object

messaging_product*

string

Required only for Cloud API. Messaging service used for the request. Use "whatsapp".

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.

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

Name
Type
Description

type*

string

Message type: location

to*

string

Recipient wa_id

location*

object

{
    "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

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

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

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

Name
Type
Description

type*

string

Message type: contacts

to*

string

Recipient wa_id

contacts*

object

{
    "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

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

Name
Value

partner_id

The ID of the Partner.

Example: examplePA

channel_id

The ID of the channel.

Example:exampleCH

Body Parameters

Name
Type
Description

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

curl --request POST \
  --url https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "block_users": [
    {
      "user": "string"
    }
  ]
}'

Response

MIXED SUCCESS/FAILURE (400)

{
  "meta": {
    "developer_message": "string",
    "http_code": 0,
    "success": true
  },
  "status_code": 0,
  "data": {
    "messaging_product": "string",
    "block_users": {
      "added_users": [
        {
          "input": "string",
          "wa_id": "string"
        }
      ],
      "removed_users": [
        {
          "input": "string",
          "wa_id": "string"
        }
      ],
      "failed_users": [
        {
          "input": "string",
          "wa_id": "string",
          "errors": [
            {
              "message": "string",
              "code": 0,
              "error_data": {
                "details": "string"
              }
            }
          ]
        }
      ]
    },
    "errors": {
      "message": "string",
      "type": "string",
      "code": 0,
      "error_data": {
        "details": "string"
      },
      "fbtrace_id": "string"
    }
  }
}
{
  "detail": {
    "<location>": {
      "<field_name>": [
        "string"
      ]
    }
  },
  "message": "string"
}

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

Name
Value

partner_id

The ID of the Partner.

Example: examplePA

channel_id

The ID of the channel.

Example:exampleCH

Body Parameters

Name
Type
Description

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

curl --request DELETE \
  --url https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users \
  --header 'Accept: application/json'

Response

{
  "meta": {
    "developer_message": "string",
    "http_code": 0,
    "success": true
  },
  "status_code": 0,
  "data": {
    "messaging_product": "string",
    "block_users": {
      "added_users": [
        {
          "input": "string",
          "wa_id": "string"
        }
      ],
      "removed_users": [
        {
          "input": "string",
          "wa_id": "string"
        }
      ],
      "failed_users": [
        {
          "input": "string",
          "wa_id": "string",
          "errors": [
            {
              "message": "string",
              "code": 0,
              "error_data": {
                "details": "string"
              }
            }
          ]
        }
      ]
    },
    "errors": {
      "message": "string",
      "type": "string",
      "code": 0,
      "error_data": {
        "details": "string"
      },
      "fbtrace_id": "string"
    }
  }
}
{
  "detail": {
    "<location>": {
      "<field_name>": [
        "string"
      ]
    }
  },
  "message": "string"
}

Not Found

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

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

Name
Value

partner_id

The ID of the Partner.

Example: examplePA

channel_id

The ID of the channel.

Example:exampleCH

Example Request

curl --request GET \
  --url https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/block_users \
  --header 'Accept: application/json'

Response

{
  "meta": {
    "developer_message": "string",
    "http_code": 0,
    "success": true
  },
  "status_code": 0,
  "data": {
    "block_users": [
      {
        "input": "string",
        "wa_id": "string"
      }
    ]
  }
}
{
  "detail": {
    "<location>": {
      "<field_name>": [
        "string"
      ]
    }
  },
  "message": "string"
}

[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.

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.

Unblock Users

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.

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.

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" : "16315551000@s.whatsapp.net" } ], "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.

See .

See .

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

See

See

See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
sending a Template message
.
location object.
contacts object.
Location Object
Location Object
Contacts Object.
Contacts Object.
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers