Address Messages

Updated: Jul 2, 2026

Copy for LLM

This feature is only available for businesses based in India and their India customers.

Address messages give your users a simpler way to share the shipping address with the business on WhatsApp.

Address messages are interactive messages that contain four parts: header, body, footer, and action. Inside the action component, specify the name address_message and the relevant parameters.

The address message supports the following fields.

Field Name	Display Label	Input Type	Supported Countries	Limitations
`name`	Name	text	India	None
`phone_number`	Phone Number	tel	India	Valid phone numbers only
`in_pin_code`	Pin Code	text	India	Max length: 6
`house_number`	Flat/House Number	text	India	None
`floor_number`	Floor Number	text	India	None
`tower_number`	Tower Number	text	India	None
`building_name`	Building/Apartment Name	text	India	None
`address`	Address	text	India	None
`landmark_area`	Landmark/Area	text	India	None
`city`	City	text	India	None
`state`	State	text	India	None

Sample API call

This is a sample API call for the address message. The country attribute is a mandatory field in the action parameters. If the country attribute is not included, there will be a validation error.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you'd like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "<COUNTRY_ISO_CODE>"
      }
    }
  }
}'

Error handling

If the area code of the phone number for the given country is not correct, businesses cannot request the address message from the recipient. For example, businesses cannot request an address message from a recipient that has the country as “India” but has a phone number with an area code of “65”.

Once the address message is sent, the business waits for the user to fill in the address and send it back. The webhook registered in the setup process shares the address the user entered.

Address message steps

The steps involved in an Address Message are the following:

Business sends an address message with the action name address_message to the user.

User interacts with the message by clicking on the CTA, which brings up an Address Message screen. The user fills out their address and submits the form.

After the user submits the address message form, the partner receives a webhook notification, which contains the details of the address the user submitted.

Sample India address message

JioMart WhatsApp chat showing catalog and order messages ending with a 'Provide address' button

WhatsApp 'Provide address' form with name and mobile number prefilled and empty address fields

Completed WhatsApp 'Provide address' form with address details filled and an active Send address button

JioMart WhatsApp chat showing the submitted address summary in the conversation

The following sequence diagram shows a typical integration flow for an address message.

Sequence diagram of the address message API flow between Partner, WhatsApp, User, and User Interactions

Additional action parameters

You can pass additional attributes such as values, validation_errors, or saved_addresses as part of the interactive action parameters. You can find information on how to use each parameter below.

Action Parameter	Usage
`values`	Businesses prefill this for address fields (for example, prefilling the city address field with “India”)
`saved_addresses`	Businesses can pass in saved addresses previously associated with the user. For users, they are presented with the option to choose the saved address instead of manually filling it in
`validation_errors`	Businesses can throw errors in the address fields and WhatsApp will prevent the user from submitting the address until all issues are resolved.

Send an address message to a user

Use the Messages API to send an end-to-end encrypted address message to the user:

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you'd like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": "JSON Payload"
    }
  }
}'

To send an address message without any saved addresses, WhatsApp will prompt the user or business with an address form to enter a new address.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you'd like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "<CUSTOMER_NAME>",
          "phone_number": "+91xxxxxxxxxx"
        }
      }
    }
  }
}'

To send an address message with saved addresses, WhatsApp will prompt the user or business with an option to select among the saved addresses or add an address option. Users can ignore the saved address and enter a new address.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you'd like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "saved_addresses": [
          {
            "id": "address1",
            "value": {
              "name": "<CUSTOMER_NAME>",
              "phone_number": "+91xxxxxxxxxx",
              "in_pin_code": "400063",
              "floor_number": "8",
              "building_name": "",
              "address": "Wing A, Cello Triumph,IB Patel Rd",
              "landmark_area": "Goregaon",
              "city": "Mumbai"
            }
          }
        ]
      }
    }
  }
}'

Check your response

A successful response includes a messages object with an ID for the newly created message.

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

An unsuccessful response contains an error message. See Error and Status Codes for more information.

Send an address message with validation errors

Re-send the address message to the user in the case of a validation error on the business server. The business should send back the set of values previously entered by the user, along with the respective validation errors for each invalid field, as shown in the sample payloads below.

curl -X  POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d
'{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "91xxxxxxxxxx",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Thanks for your order! Tell us what address you'd like this order delivered to."
    },
    "action": {
      "name": "address_message",
      "parameters": {
          "country": "IN",
          "values": {
             "name": "CUSTOMER_NAME",
             "phone_number": "+91xxxxxxxxxx",
             "in_pin_code": "666666",
             "address": "Some other location",
             "city": "Delhi"
          },
          "validation_errors": {
             "in_pin_code": "We could not locate this pin code."
          }
       }
    }
  }
}'

Receive notifications for address submissions

You receive address submission notifications through webhooks, such as the webhook notification shown below.

{
  "messages": [
    {
      "id": "gBGGFlAwCWFvAgmrzrKijase8yA",
      "from": "<PHONE_NUMBER>",
      "interactive": {
        "type": "interactive",
        "action": "address_message",
        "nfm_reply": {
          "name": "address_message",
          "response_json": "<response_json from client>",
          "body": "<body text from client>"
        },
        "timestamp": "1670394125"
      }
    }
  ]
}

The webhook notification has the following values.

Field Name	Type	Description
`interactive`	Object	Holds the response from the client
`type`	String	Would be `nfm_reply` indicating it is a Native Flow Response (NFM) from the client
`nfm_reply`	Object	Holds the data received from the client
`response_json`	String	The values of the address fields filled by the user in JSON format that are always present
`body` (Optional)	String	Body text from client, what the user sees
`name` (Optional)	String	Would be `address_message` indicating the type of NFM action response from the client

The following example shows an address message reply as an NFM response for an India address message request.

{
  "messages": [
    {
      "context": {
        "from": "FROM_PHONE_NUMBER_ID",
        "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgARGBI3NjNFN0U5QzMzNDlCQjY0M0QA"
      },
      "from": "<PHONE_NUMBER>",
      "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgASGCA5RDhBNENEMEQ3RENEOEEzMEI0RUExRDczN0I1NThFQwA=",
      "timestamp": "1671498855",
      "type": "interactive",
      "interactive": {
        "type": "nfm_reply",
        "nfm_reply": {
          "response_json": "{\"saved_address_id\":\"address1\",\"values\":{\"in_pin_code\":\"400063\",\"building_name\":\"\",\"landmark_area\":\"Goregaon\",\"address\":\"Wing A, Cello Triumph, IB Patel Rd\",\"city\":\"Mumbai\",\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+91xxxxxxxxxx\",\"floor_number\":\"8\"}}",
          "body": "CUSTOMER_NAME\n +91xxxxxxxxxx\n 400063, Goregaon, Wing A, Cello Triumph,IB Patel Rd, Mumbai, 8",
          "name": "address_message"
        }
      }
    }
  ]
}

Feature not supported

In the case where the client does not support address_message, WhatsApp silently drops the messages and sends an error message back to the business in a webhook. WhatsApp sends the following webhook notification:

{
  "statuses": [
    {
      "errors": [
        {
          "code": 1026,
          "href": "/docs/whatsapp/api/errors",
          "title": "Receiver Incapable"
        }
      ],
      "id": "gBGGFlAwCWFvAgkyHMGKnRu4JeA",
      "message": {
        "recipient_id": "+91xxxxxxxxxx"
      },
      "recipient_id": "91xxxxxxxxxx",
      "status": "failed",
      "timestamp": "1670394125",
      "type": "message"
    }
  ]
}