The Structured Information Template from Messenger Platform allows you to get customer information for shipping purposes within an existing conversation. This document shows you how to use this template.
The Structured Information template allows you to send a customer a message that contains a form that gathers the customer's shipping information. You can select the fields you need, make fields required or optional, and receive webhooks with this information when the customer submits the form. When the customer submits the form, the Send API sends the information to your business and Meta sends a notification to your webhooks server with the information.
![]() | ![]() | ![]() |
This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.
You will need:
messaging_customer_information
webhook To send the template to a customer, send a POST
request to the /PAGE-ID/messages
endpoint with the recipient.id
set to the customer's Page-scoped ID. In the message
attachment.payload
property set template_type
to customer_information
, countries
to a list of countries your business is allowed to collect address information, business_privacy
to the URL for the business' privacy policy, and expires_in_days
to up to 7 days.
curl -X POST -H "Content-Type: application/json" -d '{ "recipient": { "id": "CUSTOMER-PAGE-SCOPED-ID" }, "message": { "attachment": { "type": "template", "payload": { "template_type": "customer_information", "countries": [ "US" ], "business_privacy": { "url": "PRIVACY-POLICY-URL" }, "expires_in_days": 1 } } } }' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"
Note: The countries
property defaults to all available countries if not included in your API call. The expires_in_days
property defaults to 1
if not included in your API call.
The following table contains the properties for the template.
Property | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
| Allows you to specify whether an address form field is required and to set the field label in the Confirm address form. Maximum length of 85 characters for all customer field inputs except postal code with a maximum length of 10 characters. Possible keys:
Each
| ||||||||
| Required. An object with key | ||||||||
| Allows you to specify whether a field is required,
| ||||||||
|
A comma separated list of
two letter codes for countries
| ||||||||
| The number of days before the request for shipping information will expire. Values can be from 1 to 7. Defaults to | ||||||||
| Required. Value must be | ||||||||
SHIPPING } | Sets the template title, subtitle, and button text. Defaults to |
To send a template with required fields, send a POST
request to the /PAGE-ID/messages
endpoint like the example above and include the contact_overrides
and address_overrides
arrays with the form fields you would like to set. For example, in the following API call, we are requiring an email address and the first address line for all countries but making the second address line optional in all countries except Vietnam. We are requiring the second address line for Vietnam.
curl -X POST -H "Content-Type: application/json" -d '{ "recipient": { "id": "CUSTOMER-PAGE-SCOPED-ID" }, "message": { "attachment": { "type": "template", "payload": { "template_type": "customer_information", "countries": [], "contact_overrides": [ { "email": { "required": true } } ], "address_overrides": [ { "overrides": [ { "address_line_1": { "required": true, "label": "ADDRESS_LINE_1" } } ] }, { "country": "VN", "overrides": [ { "address_line_2": { "required": true, "label": "NEARBY_LANDMARK" } } ] } ], "business_privacy": { "url": "https://www.facebook.com/privacy/explanation" }, "expires_in_days": 1 } } } }'"https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"
You will receive the following notification when a customer submits the form and your app is subscribed to the messaging_customer_information
webhook.
{ "object": "page", "entry": [ { "time": TIMESTAMP, "id": PAGE-ID", "messaging": [ { "sender": { "id": "CUSTOMER-PAGE-SCOPED-ID" }, "recipient": { "id": "PAGE-ID" }, "timestamp": "TIMESTAMP", "messaging_customer_information": { "screens": [ { "screen_id": "Add address", "responses": [ { "key": "country", "value": "CUSTOMER-COUNTRY" }, { "key": "locality", "value": "CUSTOMER-CITY-VILLAGE" }, { "key": "administrative_area", "value": "CUSTOMER-STATE-PROVINCE" }, { "key": "shipping_notes", "value": "ADDITIONAL-NOTES-FROM-CUSTOMER" }, { "key": "phone", "value": "CUSTOMER-PHONE" }, { "key": "name", "value": "CUSTOMER-NAME" }, { "key": "address_line_1", "value": "CUSTOMER-STREET-ADDRESS" }, { "key": "postal_code", "value": "CUSTOMER-POSTAL-CODE" }, { "key": "email", "value": "CUSTOMER-EMAIL@EXAMPLE.COM" } ] } ] } } ] } ] }
Different countries have different input forms and required fields. The following tables list the address properties for a specific country's address intake form, labels for each form field, and, if no address override objects are set, the default required fields.
All input values are a string up to 85 characters in length unless otherwise stated.
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | STATE | false | State |
locality | CITY | true | City |
postal_code | POSTAL_CODE | false | Postal Code – Input is 4 to 10 characters |
sublocality | VILLAGE_NEIGHBORHOOD_QUARTER | false | Village/Neighborhood/Quarter |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | PROVINCE | true | Province |
locality | CITY_MUNICIPALITY | false | City/Municipality |
postal_code | POSTAL_CODE | true | Postal Code – Input is 7 numbers |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | TOWN | true | Town |
locality | LOCALITY | false | Locality |
postal_code | POSTAL_CODE | true | Postal Code – Input is 5 numbers |
subadministrative_area | CODEX_DELIVERY_OFFICE | false | Codex delivery office |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | STATE | true | State |
locality | CITY_VILLAGE | true | City/Village |
postal_code | PIN_CODE | true | PIN code – Input is 6 numbers |
subadministrative_area | DISTRICT_AND_OR_TALUK | false | District and/or Taluk |
sublocality | LOCALITY | false | Locality |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | PROVINCE | false | Province |
locality | VILLAGE_DESA_OR_KELURAHAN | true | Village (Desa or Kelurahan) |
postal_code | POSTAL_CODE | true | Postal code – Input is 5 numbers |
subadministrative_area | CITY_OR_REGENCY | true | City or Regency |
sublocality | SUBDISTRICT_KECAMATAN | true | Subdistrict (Kecamatan) |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | PROVINCE_CITY | false | Province/City |
locality | VILLAGE_NEIGHBORHOOD_QUARTER | false | Village/Neighborhood/Quarter |
postal_code | CODIGO_POSTAL | true | Código postal – Input is 5 numbers |
subadministrative_area | CITY | true | City |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | PROVINCE | true | Province |
locality | BARAGGAY_DISTRICT_VILLAGE | false | Barangay/District/Village |
postal_code | ZIP | false | Zip – Input is 5 numbers or 5 numbers, a hypen, and 4 numbers |
subadministrative_area | CITY_MUNICIPALITY | true | City/Municipality |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | TOWN | true | Town |
postal_code | POSTCODE | false | Postcode – Input is 6 numbers |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | PROVINCE | true | Province |
locality | VILLAGE_AND_DISTRICT_AMPHOE_KHET | true | Village and District (Amphoe/Khet) |
postal_code | POSTAL_CODE | false | Postal Code – Input is 1 to 10 characters |
sublocality | SUBDISTRICT_TAMBON_KHWAENG | false | Subdistrict (Tambon/Khwaeng) |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | COUNTY | false | County |
locality | LOCALITY | false | Locality |
postal_code | POST_CODE | true | Post code – Input is up to 8 characters |
subadministrative_area | POSTAL_TOWN | true | Postal Town |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | true | Address Line 1 |
address_line_2 | ADDRESS_LINE_2 | false | Address Line 2 |
administrative_area | STATE | true | State – Input is selected from a dropdown menu |
locality | CITY | true | City |
postal_code | ZIP | false | Zip – Input is 5 numbers or 5 numbers, a hypen, and 4 numbers |
Overide Property
|
|
required
|
Form Label
|
---|---|---|---|
address_line_1 | ADDRESS_LINE_1 | false | Address Line 1 |
administrative_area | PROVINCE_CITY | true | Province/City |
locality | LOCALITY_COMMUNE_PRECINCT | true | Locality/commune/precinct |
subadministrative_area | DISTRICT_AND_OR_TOWN | true | District and/or Town |