List Template

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": "mid.$cAAJsujCd2ORj_1qmrFdzhVa-4cvO"
}  

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.