List Template Reference

The list template allows you to send a structured message with a set of items rendered vertically. For implementation details, see List Template.

Contents

Request URI

https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>

Example Request

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": true,
              "webview_height_ratio": "tall",
              "fallback_url": "https://peterssendreceiveapp.ngrok.io/"
            }
          },
          {
            "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"
}  

Properties

recipient

Description of the message recipient. All requests must include one of id, phone_number, or user_ref.

Property Type Description

recipient.id

String

PSID of the message recipient. Either PSID or phone_number must be set.

recipient.phone_number

String

Optional. Phone number of the recipient with the format +1(212)555-2368.


Your bot must be approved for Customer Matching to send messages this way.

recipient.user_ref

String

Optional. user_ref from the checkbox plugin.

recipient.name

Object

Optional. Used only if phone_number is set. Specifies the person's name in the format:


{"first_name":"John", "last_name":"Doe"}

Providing a name increases the odds of a successful match.

message

Description of the message to be sent.
Property Type Description

message.attachment

Object

An object describing attachments to the message.

message.attachment

Property Type Description

type

String

Value must be template

payload

Object

payload of the template.

message.attachment.payload

Property Type Description

template_type

String

Value must be list

top_element_style

String

Optional. Sets the format of the first list items. Messenger web client currently only renders compact.


compact: Renders a plain list item.


large: Renders the first list item as a cover item.

buttons

Array<button>

Optional. Button to display at the bottom of the list. Maximum of 1 button is supported.

elements

Array<element>

Array of objects that describe items in the list.


Minimum of 2 elements required. Maximum of 4 elements is supported.

message.attachment.payload.elements

Property Type Description

title

String

String to display as the title of the list item. 80 character limit. May be truncated if the title spans too many lines.


Element must also have one or both of image_url or subtitle set.

subtitle

String

Optional. String to display as the subtitle of the list item. 80 character limit. May be truncated if the subtitle spans too many lines.


Element must have one or both of image_url or subtitle set.

image_url

String

Optional. URL of the image to display in the list item.


Element must have one or both of image_url or subtitle set.

default_action

Object

Optional. URL button that specifies the default action to execute when the list item is tapped.