Sending Address Messages

You can use the messages node to send address messages to your customers.

This guide teaches you how to send the address message. Address messages give your users a simpler way to share the shipping address with the business on WhatsApp.

To capture addresses in the WA API, the partner should start from configuring WA API as described in WA API Getting Started guide.

Before You Start

You need to meet all the prerequisites listed in the Before You Start section of the Messages documentation.

Address messages are interactive messages that contain the 4 main parts: header, body, footer, and action. Inside the action component business specifies the name “address_message” and relevant parameters.

Currently address messages are supported in the following two countries: India and Singapore. Below table outlines which fields are supported in which country specifically.

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 it is not included, there will be a validation error.

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "native_flow",
    "header": {
      "text": "your-text-header-content"
    }
    "body": {
      "text": "your-text-body-content"
    },
    "footer": {
      "text": "your-text-footer-content"
    },
    "action": {
      "name": "address_message",
      "parameters": {
            "country": "<country>",
       }
    }
  }
}

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

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

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

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.

Send Address Message to a User

Make a POST Request to /messages using the WhatsApp API to send an end-to-end encrypted address message to the user:

POST /v1/messages
{
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "header": {
      "text": "your-text-header-content"
    },
    "body": {
      "text": "your-text-body-content"
    },
    "footer": {
      "text": "your-text-footer-content"
    },
    "action": {
      "name": "address_message",
      "parameters": "your-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.

India

POST /v1/messages
{
  "to": "PHONE_NUMBER",
  "recipient_type": "individual",
  "interactive": {
    "type": "address_message",
    "header": {
      "text": "header"
    },
    "body": {
      "text": "body"
    },
    "footer": {
      "text": "footer"
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "CUSTOMER_NAME",
          "phone_number": "+91xxxxxxxxxx"
        },
        "saved_addresses": [
          {
            "id": "address_id",
            "value": {
              "name": "CUSTOMER_NAME",
              "phone_number": "+91xxxxxxxxxx",
              "in_pin_code": "11001",
              "house_number": "104",
              "floor_number": "3",
              "tower_number": "1",
              "building_name": "Delhi Tower",
              "address": "Janpath Rd",
              "landmark_area": "Khurshid Lal",
              "city": "Delhi"
            }
          }
        ]
      }
    }
  }
}

Singapore

POST /v1/messages  
{
  "to": "PHONE_NUMBER",
  "recipient_type": "individual",
  "interactive": {
    "type": "address_message",
    "header": {
      "text": "header"
    },
    "body": {
      "text": "body"
    },
    "footer": {
      "text": "footer"
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "SG",
        "values": {
          "name": "CUSTOMER_NAME",
          "phone_number": "+65xxxxxxxx"
        },
        "saved_addresses": [
          {
            "id": "address_id",
            "value": {
              "name": "CUSTOMER_NAME",
              "phone_number": "+65xxxxxxxx",
              "address": "9 StraitsView, MarinaOne WestTower",
              "unit_number": "1234",
              "sg_post_code": "018937",
              "city": "Singapore"
            }
          }
        ]
      }
    }
  }
} 

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

POST /v1/messages 
{
  "to": "PHONE_NUMBER",
  "recipient_type": "individual",
  "interactive": {
    "type": "address_message",
    "header": {
      "text": "header"
    },
    "body": {
      "text": "body"
    },
    "footer": {
      "text": "footer"
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN",
        "values": {
          "name": "CUSTOMER_NAME",
          "phone_number": "+91xxxxxxxxxx"
        },
        "saved_addresses": [
          {
            "id": "address_id",
            "value": {
              "name": "CUSTOMER_NAME",
              "phone_number": "+91xxxxxxxxxx",
              "in_pin_code": "11001",
              "house_number": "104",
              "floor_number": "3",
              "tower_number": "1",
              "building_name": "Delhi Tower",
              "address": "Janpath Rd",
              "landmark_area": "Khurshid Lal",
              "city": "Delhi"
            }
          }
        ]
      }
    }
  }
}

Singapore

POST /v1/messages 
{
  "to": "PHONE_NUMBER",
  "recipient_type": "individual",
  "interactive": {
    "type": "address_message",
    "header": {
      "text": "header"
    },
    "body": {
      "text": "body"
    },
    "footer": {
      "text": "footer"
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "SG",
        "values": {
          "name": "CUSTOMER_NAME",
          "phone_number": "+65xxxxxxxx"
        },
        "saved_addresses": [
          {
            "id": "address_id",
            "value": {
              "name": "CUSTOMER_NAME",
              "phone_number": "+65xxxxxxxx",
              "address": "9 StraitsView, MarinaOne WestTower",
              "unit_number": "1234",
              "sg_post_code": "018937",
              "city": "Singapore"
            }
          }
        ]
      }
    }
  }
} 

Check Your Response

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

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

An unsuccessful response contains an error message. See Error and Status Codes 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

POST /v1/messages  
{
  "to": "+91xxxxxxxxxx",
  "recipient_type": "individual",
  "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": "Delhi"
        },
        "validation_errors": {
          "in_pin_code": "We could not locate this pin code."
        }
      }
    }
  }
} 

Singapore

POST /v1/messages     
{
 "to": "+65xxxxxxxx",
  "recipient_type": "individual",
  "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.

An address message reply as an NFM response type for an India address message request is shown below.

{
 "messages": [
   {
     "id": "gBGGFlAwCWFvAgmrzrKijase8yA",
     "from": "+913850881995",
     "Interactive": {
       "type": "nfm_reply",
       "nfm_reply": {
         "name": "address_message",
         "response_json": {
           "saved_address_id": "address_id",
           "values": {
             "address": "Link Road, Malad (West)",
             "tower_number": "A",
             "city": "Mumbai",
             "house_number": "2",
             "name": "Devi Salim",
             "state": "state",
             "in_pin_code": "400064",
             "building_name": "Eureka Tower",
             "floor_number": "9",
             "landmark_area": "Behind Evershine Mall",
             "phone_number": "+913850881995"
           }
         },
         "body": "Devi Salim\n+913850881995\n400064, 2, 3, A, Eureka Tower, Link Road, Malad (West), Behind Evershine Mall, Mumbai, state"
       }
     },
 "meta": {
   "api_status": "stable",
   "version": "2.38.0"
 }
}  

Feature Not Supported

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:

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