Contacts & 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 .

How to send 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".

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:

How to send 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.

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:

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.

Use this endpoint 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.

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

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

PreviousAddress Messages (India and Singapore only)NextTemplate Messages

Last updated 8 days ago

Was this helpful?