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

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.

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