Skip to content

This term

Address Message

An interactive WhatsApp message that opens a native form for the customer's delivery address and returns it to the business as structured fields.

Also called: address_message · Interactive address message · WhatsApp address form

Often confused with

Location Request Message

An interactive WhatsApp message with a Send location button that asks the user to share where they are, returning their pin as a reply.

Read the Location Request Message entry

Read an address request, field by field

7 / 7
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919812345678",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "That pin code is outside our delivery area. Please choose another address for order #A2041."
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "Ananya",
          "phone_number": "+919812345678",
          "in_pin_code": "176310",
          "city": "Chamba"
        },
        "saved_addresses": [
          {
            "id": "home",
            "value": {
              "name": "Ananya",
              "phone_number": "+919812345678",
              "in_pin_code": "411045",
              "house_number": "B-1203",
              "building_name": "Sunrise Heights",
              "address": "Baner Road",
              "landmark_area": "Baner",
              "city": "Pune",
              "state": "Maharashtra"
            }
          }
        ],
        "validation_errors": {
          "in_pin_code": "We don't deliver to this pin code yet. Please enter another address."
        }
      }
    }
  }
}
A real-shaped address_message send: a second attempt that prefills the form, offers a saved address and flags an unserviceable pin code. Step through the fields that decide what the customer sees.

Field 7: interactive.action.parameters.validation_errors.in_pin_code — Your own serviceability check failed. WhatsApp shows this text on the field and blocks submission until it changes.

What is an address message?

An address message is an interactive message type on the WhatsApp Cloud API (interactive.type: "address_message"). The customer sees your body text and a button; tapping it opens a native address form inside WhatsApp with labelled fields (name, phone number, pin code, house number, floor, tower, building, street address, landmark or area, city and state). When the customer submits, the answers reach your webhook as structured data instead of a free-typed paragraph.

Meta's documentation limits the feature to businesses based in India and their customers in India, so the recipient needs an Indian (+91) number. The country attribute is mandatory and set to IN, which selects the Indian field set with its six-character in_pin_code. You can prefill fields with values, offer addresses the customer used before with saved_addresses, and send the form again with validation_errors (for example to say a pin code is outside your delivery area); WhatsApp then blocks submission until the flagged field is changed. For customers outside India, collect the address with a WhatsApp Flow or a plain text prompt instead.

Like every non-template interactive message, it can only be sent while the 24-hour customer service window is open, so it usually follows a customer message or a tap on a template button. It is often confused with the location request message, which asks for a GPS pin. A pin tells a rider where to go; an address message produces the postal fields that a courier label and a serviceability check need.

Key takeaways

  • An address message is an interactive Cloud API message that opens a native WhatsApp form and returns the address as structured fields.
  • Meta documents it only for businesses based in India messaging customers in India, and the country parameter (IN) is mandatory.
  • It is a non-template message, so it can be sent only inside an open 24-hour customer service window.
  • The reply arrives as interactive.type: "nfm_reply", with the address as a JSON string in nfm_reply.response_json.
  • Send the form back with validation_errors to block an unserviceable pin code before the order ships.

An address message in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919812345678",
    "type": "interactive",
    "interactive": {
      "type": "address_message",
      "body": { "text": "Where should we deliver order #A2041? Tap below to add your address." },
      "action": {
        "name": "address_message",
        "parameters": {
          "country": "IN",
          "values": { "name": "Ananya", "phone_number": "+919812345678" },
          "saved_addresses": [
            {
              "id": "home",
              "value": {
                "name": "Ananya",
                "phone_number": "+919812345678",
                "in_pin_code": "411045",
                "house_number": "B-1203",
                "building_name": "Sunrise Heights",
                "address": "Baner Road",
                "landmark_area": "Baner",
                "city": "Pune",
                "state": "Maharashtra"
              }
            }
          ]
        }
      }
    }
  }'

An address message that prefills the name and number and offers one saved address.

How does an address message work?

  1. Step 1

    Open the window first

    The customer messages you, or taps a quick-reply button on a utility template such as an order confirmation. The address message is a session message, so it needs that open 24-hour window.

  2. Step 2

    Send the address form

    POST to /{PHONE_NUMBER_ID}/messages with type: "interactive", interactive.type: "address_message", body text, and action.name: "address_message" with parameters.country: "IN". Add values to prefill known fields and saved_addresses to offer earlier ones.

  3. Step 3

    The customer fills the native form

    WhatsApp shows labelled fields, checks basics such as a valid phone number and a pin code of at most 6 digits, and lets the customer pick a saved address or type a new one.

  4. Step 4

    Receive the reply

    Your webhook gets a messages event with type: "interactive" and interactive.type: "nfm_reply". The address arrives as a JSON string in nfm_reply.response_json, and nfm_reply.name is address_message.

  5. Step 5

    Validate, then confirm or send it back

    Parse response_json, check the pin code against your courier's serviceable list, and either attach the address to the order or send the form again with validation_errors keyed by field, such as in_pin_code.

An address message: key facts and limits

Message type
interactive.type = address_message
Availability
India only: India-based businesses messaging customers in India
Required parameter
country, set to IN
India fields
name, phone_number, in_pin_code, house_number, floor_number, tower_number, building_name, address, landmark_area, city, state
Pin code field
in_pin_code, at most 6 characters
Reply
interactive.type = nfm_reply, address in response_json (a string)
Unsupported client
Failed status with error 1026 (Receiver Incapable)
When it can be sent
Only inside an open 24-hour customer service window

Common mix-ups

Common mistakes with an address message

  • Sending it outside the window

    An address message is not a template. If the customer has not messaged you in the last 24 hours the send fails; open the window with a utility template (an order confirmation with quick replies) and send the form after the customer taps.

  • Treating response_json as an object

    response_json is a string. Parse it before reading values, and handle both a newly typed address and a pick from your saved list (saved_address_id).

  • Trusting the form for serviceability

    WhatsApp checks format (pin-code length, a valid phone number), not whether your courier delivers there. Check the pin code yourself and send the form back with validation_errors when it fails.

  • No fallback for unsupported clients

    If the customer's app cannot render the form, WhatsApp drops the message and you receive a failed status with error 1026. Watch for it and fall back to asking for the address as text or through a WhatsApp Flow.

  • Losing which order the address belongs to

    The reply's context.id is the wamid of the address message you sent. Store that wamid against the order at send time, or the address arrives with nothing to attach to.

Example: Fixing addresses before dispatch in Pune

A Pune home-décor brand ships mostly cash-on-delivery. After each order it sends a utility template confirming the items; when the buyer taps Confirm, the window that tap opens lets the brand send an address message prefilled with the name and number from checkout, plus the buyer's previous address as a saved option. One buyer submits a new address with a pin code the brand's courier does not cover. The brand's check catches it and sends the form back with a validation error on in_pin_code; the buyer enters an office address instead, and the corrected fields go straight onto the courier label.

Why the difference matters

Why does an address message matter?

Many failed deliveries on Indian cash-on-delivery orders start with an address problem: a missing flat number, a wrong pin code, a landmark typed into the city field. Free-text replies have to be read by a person or parsed by a model. An address message hands your order system the same named fields every time, with basic checks done by WhatsApp and your own serviceability errors shown before the customer can submit. Cleaner addresses mean fewer non-delivery reports and fewer parcels returned to origin.

Rules of thumb

Best practices for an address message

  • Prefill everything you already know from checkout; every field the customer does not have to type raises completion.
  • Name the order number in the body text so the customer knows why you are asking.
  • Offer saved addresses to repeat buyers, but expect new ones too: gifts and office deliveries are common.
  • Log the parsed address with personal data masked; it settles courier disputes quickly.

Address Message FAQs

Can I send an address message outside the 24-hour window?+
No. It is a non-template interactive message, so it needs an open customer service window. Send a utility template first; when the customer replies or taps a button, the window opens and you can send the form.
Is the address message available outside India?+
No. Meta documents address messages only for businesses based in India messaging their customers in India, with `country` set to `IN`. For customers in other countries, collect the address with a WhatsApp Flow (a form you design) or a simple text prompt that your system parses.
How is it different from a location request message?+
A location request asks the customer to share a GPS pin; an address message collects postal fields such as pin code, building and landmark. Couriers and serviceability checks need the address, riders benefit from the pin, so some flows ask for both.
What does an address message cost?+
It is billed like any message sent inside the customer service window: in India, service messages have been charged at ₹0.145 per message since 1 October 2026.

See InfiQ pricing

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms