This feature is only available for businesses based in Singapore and their Singapore customers, and businesses based in India and their Indian customers.
Address messages are a type of interactive message used by businesses to collect or update address information from their customers.
It consists of four main components: header, body, footer, and action and Inside the action component business can specify the name “address_message” and relevant parameters.
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 button, which brings up an Address Message screen. The user fills out their address and submits the form
After the address message form is submitted by the user, the partner receives a webhook notification, which contains the details of the address submitted by the user
Sample India Address Message
Sample Singapore Address Message
The table below outlines which fields are supported in which country specifically:
Field Name
Display Label
Input Type
Supported Countries
Limitations
name
Name
text
India, Singapore
None
phone_number
Phone Number
tel
India, Singapore
Valid phone numbers only
in_pin_code
Pin Code
text
India
Max length: 6
sg_post_code
Post Code
number
Singapore
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, Singapore
None
landmark_area
Landmark/Area
text
India
None
unit_number
Unit number
text
Singapore
None
city
City
text
India, Singapore
None
state
State
text
India
None
Additional Action Parameters
The business can pass additional attributes such as values, validation_errors, or saved_addresses as part of the interactive action parameters. You can find information on each of their usage below.
Action Parameter
Usage
values
Businesses prefill this for address fields (eg. prefilling the city address field with “Singapore”)
saved_addresses
For businesses, they 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 the issue(s) are/is resolved.
Send an Address Messages
Make a POST call to /messages using the WhatsApp API to send an end-to-end encrypted address message to the user:
{"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 String 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.
India
{"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\"}}"
} } }
Singapore
{"messaging_product":"whatsapp","recipient_type":"individual","to":"+65xxxxxxxxxx","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\":\"SG\",\"values\":{\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+65xxxxxxxxxx\"}}"
} } }
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.
India
{"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\"}}]}"
} }}
Singapore
{"messaging_product":"whatsapp","recipient_type":"individual","to":"+65xxxxxxxxxx","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\":\"SG\",\"values\":{\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+65xxxxxxxxxx\"},\"saved_addresses\":[{\"id\":\"address1\",\"value\":{\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+65xxxxxxxxxx\",\"sg_post_code\":\"018937\",\"address\":\"9 Straits View, Marina One West Tower\",\"unit_number\":\"Suite 29-00\",\"city\":\"Singapore\"}}]}"
} }}
Check Your Response
A successful response includes a messages object with an ID for the newly created message.
An unsuccessful response contains an error message. See Error Messages for more information.
Send an Address Message with Validation Errors
An address message should be re-sent 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.
India
{"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\": \"Honolulu\"},\"validation_errors\": {\"in_pin_code\": \"We could not locate this pin code.\"}}"
} }}
Singapore
{"messaging_product":"whatsapp","recipient_type":"individual","to":"12065550107","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\": \"SG\",\"values\": {\"name\": \"CUSTOMER_NAME\",\"phone_number\": \"+65xxxxxxxxxx\",\"sg_post_code\": \"666666\",\"address\": \"Some other location\",\"city\": \"Singapore\"},\"validation_errors\": {\"sg_post_code\": \"We could not locate this pin code.\"}}"
} }}
Receive Notifications for Address Submissions
Businesses will receive address submission notifications through webhooks, such as the one shown below.
{"messages": [ {"id":"gBGGFlAwCWFvAgmrzrKijase8yA","from":"PHONE_NUMBER","Interactive": {"type":"nfm_reply","action":"address_message","nfm_reply": {"name":"address_message","response_json": “<response_json from client>”,"body": “<body text from client>”, }"timestamp": "1670394125","type":"interactive" } ]}
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
An address message reply as an NFM response type for an India address message request is show below.
In the case where the client does not support address_message, messages are silently dropped and an error message is sent back to the business in a webhook. The webhook notification that would be sent back is shown below:
[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.
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.
An address message should be re-sent 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.
India
POST /v1/messages {"to":"+91xxxxxxxxxx","recipient_type":"individual","type":"interactive","interactive": {"type":"address_message","body": {"text":"We weren't able to locate your address. Please try again." },"action": {"name":"address_message","parameters": {"country":"IN","values": {"name":"CUSTOMER_NAME","phone_number":"+91xxxxxxxxxx","in_pin_code":"666666","address":"Some other location","city":"Honolulu" },"validation_errors": {"in_pin_code":"We could not locate this pin code." } } } }}
Singapore
POST /v1/messages {"to":"+65xxxxxxxx","recipient_type":"individual","type":"interactive","interactive": {"type":"address_message","body": {"text":"We weren't able to locate your address. Please try again." },"action": {"name":"address_message","parameters": {"country":"SG","values": {"name":"CUSTOMER_NAME","phone_number":"+65xxxxxxxx""sg_post_code": "666666","address":"Some other location","city":"Singapore" },"validation_errors": {"sg_post_code":"We could not locate this pin code." } } } }}
Receive Notifications for Address Submissions
Businesses will receive address submission notifications through webhooks, such as the one shown below.
{"messages": [ {"id":"gBGGFlAwCWFvAgmrzrKijase8yA","from":"PHONE_NUMBER","Interactive": {"type":"nfm_reply","action":"address_message","nfm_reply": {"name":"address_message","response_json": <response_json from client>,"body": <body text from client>, }"timestamp": "1670394125","type":"interactive" } ]}
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
An address message reply as an NFM response type for an India address message request is show below.
In the case where the client does not support address_message, messages are silently dropped and an error message is sent back to the business in a webhook. The webhook notification that would be sent back is shown below:
Dry-run is a mode for Interactive Messages to understand the capability of the receiver for a particular feature. In order to use this mode, business needs to send the request template outlined below:
They will then receive a webhook response indicating whether the receiver is capable of receiving the message or not:
POST /v1/messages {"statuses": [ {"errors": [ {"code":"1026 | 1030", "title": "Receiver is incapable of receiving this message | Receiver is capable of receiving this message",
"details":"Address_Message", } ],"status":"failed","timestamp":"1632164533", “message”: {"recipient_id":"<account number>" }"type": "message" } ]}
Error Code
Description
1026
Receiver is incapable of rendering the Address capture message.
1030
Receiver can/capable rendering the Address capture message.
