Structured Information Template

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.

Overview

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.

Before You Start

本指南假设您已经查看 Messenger 开放平台概览,并且已经实现发送和接收消息和通知所需的组件。

You will need:

  • The ID for the business' Facebook Page
  • The Page-scoped ID for the customer
  • A Page access token
  • A subscription to the messaging_customer_information webhook

Send the Template

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.

Attachment Payload Reference

The following table contains the properties for the template.

Property Description

address_overrides

array

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:

  • country – Value is the country the override applies to
  • overrides – Value is an array of overrides to apply
    • Possible overrides keys include:
  • address_line_1
  • address_line_2
  • administrative_area
  • locality
  • postal_code
  • subadministrative_area
  • sublocality

Each overrides key has two key-value pairs:

  • label – The label for the field that is displayed in the form
  • requiredtrue to signal this field is required; false to signal this field is not required

See the table below for specific country field information.

business_privacy

object

Required. An object with key url and value set to the URL of the business' privacy privacy policies

contact_overrides

array

Allows you to specify whether a field is required, true, or not, false, and to set the field label in the Confirm address form. Fields are pre-filled with the customer's name, email, and phone number.

Form fieldsField Label Values

name

email

EMAIL

phone

PHONE

countries

array

A comma separated list of two letter codes for countries where your business is allowed to collect customer shipping information. Defaults to all countries your business is allowed to collect shipping information.

expires_in_days

int

The number of days before the request for shipping information will expire. Values can be from 1 to 7. Defaults to 1.

template_type

string

Required. Value must be customer_information

purpose

enum { SHIPPING}

Sets the template title, subtitle, and button text. Defaults to SHIPPING.

Send a Template with Required Fields

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"

Meta Webhooks Notification

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

Address Components by Country

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.

Brazil

Overide Property
label
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

Canada

Overide Property
label
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

France

Overide Property
label
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

India

Overide Property
label
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

Indonesia

Overide Property
label
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)

Mexico

Overide Property
label
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

Phillippines

Overide Property
label
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

Singapore

Overide Property
label
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

Thailand

Overide Property
label
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)

United Kingdom

Overide Property
label
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

USA

Overide Property
label
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

Vietnam

Overide Property
label
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