--- title: Send Address Message slug: messaging-apis/send-address-message docTags: createdAt: 2025-10-06T15:08:16.699Z --- **Note**: This feature is only available for businesses based in Singapore and their Singapore customers, and businesses based in India and their India customers. Address message is an interactive messages that can be sent to collect the address from the customers by the WhatsApp Businesess. It give your users a simpler way to share the shipping address with the business on WhatsApp. Its is Free form message with a CTA button which will open a form with a pre-defined personal details and address fields. It contains 4 main parts: header, body, footer, and action. Inside the action component, the business specifies the name “address\_message” and relevant parameters. # User Journey Let us try to understand and see how does the Address message looks like with a demonstration Address Message - WhatsApp # Address Message Steps The steps involved in an Address Message are the following: 1. Business sends an address message with the action name address\_message to the user 2. 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 3. 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** ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/ug02jep4RzG5wzUB3U1RA-20260729-065205.png?1715259964) # The following sequence diagram shows a typical integration flow for an address message. # ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/uoTZHr0a8Ofcp7GQ0Pi7L-20260729-065200.jpeg?1715259956) # 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 uses below. 1. **Values**: - Businesses prefill this for address fields (eg. prefilling the city address field with “Singapore”) - 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. 2. **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. - 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. 3. **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. - 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. # Error Handling If the area code of the phone number for the given country is not correct, businesses will be unable to request the address message from the recipient. For example, businesses will be unable to request an address message from a recipient that has the country as “Singapore” but has a phone number with an area code of "91". Address messages will not allow simultaneous passing of conflicting fields. For example, you cannot pass in sg\_post\_code when the country is set to “IN”. Once the address message is sent, the business waits for the user to fill in the address and send it back. The user-entered address is shared through the webhook registered in the setup process. # Supported Fields in Country 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 https\://\{\{​AuthKey}}:\{\{​AuthToken}}@\{\{​SubDomain}}/v2/accounts/\{\{​AccountSid}}/messages using the WhatsApp API to send an end-to-end encrypted address message to the user: 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. \{ "custom\_data": "custom\_data", "status\_callback": "status\_callback\_url", "client\_id": "client\_id", "whatsapp": \{ "messages": \[ \{ "from": "9180XXXXXXXX", "to": "9198XXXXXXXX", "content": \{ "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" } } } } } ] } } ## Check Your Response A successful response includes a messages object with a **sid** for the newly created message. \{ "request\_id": "d46ba32ad89646XXXX", "method": "POST", "http\_code": 202, "metadata": \{ "failed": 0, "total": 1, "success": 1 }, "response": \{ "whatsapp": \{ "messages": \[ \{ "code": 202, "error\_data": null, "status": "success", "data": \{ "sid": "720eXXXXXXX", "client\_sid": "XXXX" } } ] } } } # Send a Pre-filled Address Message To send an address message **with a pre-filled address and** **without any saved addresses**, WhatsApp will prompt the user or business with an address form to enter a new address. **India** ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/fGMlHHYag_pCwOrcpGK04-20260729-065206.png?1715259964) \{ "custom\_data": "custom\_data", "status\_callback": "status\_callback\_url", "client\_id": "client\_id", "whatsapp": \{ "messages": \[ \{ "from": "9180XXXXXXXX", "to": "9198XXXXXXXX", "content": \{ "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": "+9198XXXXXXXX" } } } } } } ] } } # Send a Saved Address Message 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. ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/jhgts3lYtc0f-hbfe0Gr9-20260729-065202.jpeg?1715259961) ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/pKaFD-PuHFBLM5ikE4xKB-20260729-065201.jpeg?1715259961) ![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/nt0MI2aeBwOelYUYo7ymB-20260729-065203.jpeg?1715259962) \{ "custom\_data": "custom\_data", "status\_callback": "status\_callback\_url", "client\_id": "client\_id", "whatsapp": \{ "messages": \[ \{ "from": "9180XXXXXXXX", "to": "9198XXXXXXXX", "content": \{ "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": "400101", "floor\_number": "5", "building\_name": "", "address": "Wing F2, Ramada Tower, 90ft Road", "landmark\_area": "Andheri East", "city": "Mumbai" } } ] } } } } } ] } } # 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** \{ "custom\_data": "custom\_data", "status\_callback": "status\_callback\_url", "client\_id": "client\_id", "whatsapp": \{ "messages": \[ \{ "from": "9180XXXXXXXX", "to": "9198XXXXXXXX", "content": \{ "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 Callback Notifications for Address Submissions Businesses will receive address submission notifications through webhooks, such as the one shown below. ## Default & Pre-filled Address Message Callbacks \{ "whatsapp": \{ "messages": \[ \{ "callback\_type": "incoming\_message", "sid": "eff9590c15fXXXXX", "from": "+9198XXXXXXXX", "to": "+9180XXXXXXXX", "timestamp": "2024-04-08T11:19:31+05:30", "profile\_name": "XXX", "content": \{ "type": "interactive", "context": \{ "sid": "c0edd0b1b66ceXXXXXXX" }, "interactive": \{ "type": "nfm\_reply", "nfm\_reply": \{ "body": "AbhXX \n9878XXXXXX\n560XX, 2X above Dishware , Some Landmark , 201, 2, 1, Adishwar, Bangalore , karnataka ", "name": "address\_message", "response\_json": "\{\\"values\\":\{\\"in\_pin\_code\\":\\"560XX\\",\\"building\_name\\":\\"Adishwar\\",\\"landmark\_area\\":\\"Some Landmark \\",\\"address\\":\\"2X above Dishware \\",\\"tower\_number\\":\\"1\\",\\"city\\":\\"Bangalore \\",\\"name\\":\\"AbhXX \\",\\"phone\_number\\":\\"98XXXXXXXX\\",\\"house\_number\\":\\"2XX\\",\\"floor\_number\\":\\"2\\",\\"state\\":\\"Karnataka \\"}}" } } } } ] } } ## Saved Address Message Callbacks \{ "whatsapp": \{ "messages": \[ \{ "callback\_type": "incoming\_message", "sid": "0315dea17bXXXX", "from": "+9198XXXXXXXX", "to": "+9180XXXXXXXX", "timestamp": "2024-04-08T12:15:52+05:30", "profile\_name": "AbhXX", "content": \{ "type": "interactive", "context": \{ "sid": "feebe4823fXXXXX" }, "interactive": \{ "type": "nfm\_reply", "nfm\_reply": \{ "body": "CUSTOMER\_NAME\n+91xxxxxxxxxx\n400063, Wing F, Ramada Tower, 90ft Road, Andheri East, Mumbai, 8", "name": "address\_message", "response\_json": "\{\\"saved\_address\_id\\":\\"address1\\",\\"values\\":\{\\"in\_pin\_code\\":\\"400063\\",\\"landmark\_area\\":\\"Andheri\\",\\"address\\":\\"Wing F, Ramada Tower, 90ft Road\\",\\"city\\":\\"Mumbai\\",\\"name\\":\\"CUSTOMER\_NAME\\",\\"floor\_number\\":\\"8\\",\\"phone\_number\\":\\"+91xxxxxxxxxx\\"}}" } } } } ] } } 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: Copy \{ "statuses": \[ \{ "errors": \[ \{ "code": 1026, "href": "https\://developers.facebook.com/docs/whatsapp/api/errors/", "title": "Receiver Incapable" } ], "id": "gBGGFlAwCWFvAgkyHMGKnRu4JeA", "message": \{ "recipient\_id": "+91xxxxxxxxxx" }, "recipient\_id": "91xxxxxxxxxx", "status": "failed", "timestamp": "1670394125", "type": "message" } ] }