List Template

On July 29, 2019 we deprecated the List Template for V4.0

During F8 2019, we announced our plans to launch a lighter, better and simpler Messenger designed to build closer connections between people and businesses.

Starting August 15, 2019, updated versions of the Messenger app will no longer support Vertical list templates. Vertical list templates will render as horizontal scrollable carousel template post August 15th. Refer to June 10, 2019 Announcement.

The list template is a list of 2-4 structured items with an optional global button rendered at the bottom. Each item may contain a thumbnail image, title, subtitle, and one button. You may also specify a default_action object that sets a URL that will be opened in the Messenger webview when the item is tapped.

Contents

Template Payload

For a complete list of template properties, see the List Template reference.

"payload": {
  "template_type": "list",
  "top_element_style": "<LARGE | COMPACT>",
  "elements": [
    {
      "title": "<TITLE_TEXT>",
      "subtitle": "<SUBTITLE_TEXT>",
      "image_url": "<IMAGE_URL_FOR_THUMBNAIL>",          
      "buttons": [<BUTTON_OBJECT>],
      "default_action": {
        "type": "web_url",
        "url": "<URL_TO_OPEN_WHEN_ITEM_IS_TAPPED>",
        "messenger_extensions": <TRUE | FALSE>,
        "webview_height_ratio": "<COMPACT | TALL | FULL>"
      }
    },
    ...
  ],
   "buttons": [<BUTTON_OBJECT>]  
}

Disabling the Cover Image

By default, the first item in the list is rendered as a cover image with overlaid text. You may also render it as a standard list item by setting "top_element_style": "compact".

Example Request

For complete request details and properties, see the List Template Reference.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"RECIPIENT_ID"
  }, 
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "list",
        "top_element_style": "compact",
        "elements": [
          {
            "title": "Classic T-Shirt Collection",
            "subtitle": "See all our colors",
            "image_url": "https://peterssendreceiveapp.ngrok.io/img/collection.png",          
            "buttons": [
              {
                "title": "View",
                "type": "web_url",
                "url": "https://peterssendreceiveapp.ngrok.io/collection",
                "messenger_extensions": true,
                "webview_height_ratio": "tall",
                "fallback_url": "https://peterssendreceiveapp.ngrok.io/"            
              }
            ]
          },
          {
            "title": "Classic White T-Shirt",
            "subtitle": "See all our colors",
            "default_action": {
              "type": "web_url",
              "url": "https://peterssendreceiveapp.ngrok.io/view?item=100",
              "messenger_extensions": false,
              "webview_height_ratio": "tall"
            }
          },
          {
            "title": "Classic Blue T-Shirt",
            "image_url": "https://peterssendreceiveapp.ngrok.io/img/blue-t-shirt.png",
            "subtitle": "100% Cotton, 200% Comfortable",
            "default_action": {
              "type": "web_url",
              "url": "https://peterssendreceiveapp.ngrok.io/view?item=101",
              "messenger_extensions": true,
              "webview_height_ratio": "tall",
              "fallback_url": "https://peterssendreceiveapp.ngrok.io/"
            },
            "buttons": [
              {
                "title": "Shop Now",
                "type": "web_url",
                "url": "https://peterssendreceiveapp.ngrok.io/shop?item=101",
                "messenger_extensions": true,
                "webview_height_ratio": "tall",
                "fallback_url": "https://peterssendreceiveapp.ngrok.io/"            
              }
            ]        
          }
        ],
         "buttons": [
          {
            "title": "View More",
            "type": "postback",
            "payload": "payload"            
          }
        ]  
      }
    }
  }
}' "https://graph.facebook.com/me/messages?access_token=PAGE_ACCESS_TOKEN"

Example Response

{
  "recipient_id": "1254477777772919",
  "message_id": "AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}  

Best Practices

Be concise with your list and its content, since it scrolls in the same direction as the thread.

Provide a list-level action if there's a chance none of the items will meet your user's needs.

Don't use this if you don't need or want your user to see the list — if, for instance, it's ranked and likely that the first item will do the trick. Consider a Carousel instead.