Messenger Platform

Generic Template

The generic template is a simple structured message that includes a title, subtitle, image, and up to three buttons. You may also specify a default_action object that sets a URL that will be opened in the Messenger webview when the template is tapped.

Contents

Template Payload

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

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

The Messenger Platform supports the sending of a horizontally scrollable carousel of generic templates.

To create a scrollable carousel, include up to 10 generic templates in the elements array of the payload.

"payload": {
  "template_type":"generic",
  "elements":[
    <GENERIC_TEMPLATE>,
    <GENERIC_TEMPLATE>,
    ...
  ]
}

Example Request

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

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_url":"https://raw.githubusercontent.com/fbsamples/original-coast-clothing/main/public/styles/male-work.jpg",
            "subtitle":"We have the right hat for everyone.",
            "default_action": {
              "type": "web_url",
              "url": "https://www.originalcoastclothing.com/",
              "webview_height_ratio": "tall"
            },
            "buttons":[
              {
                "type":"web_url",
                "url":"https://www.originalcoastclothing.com/",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"DEVELOPER_DEFINED_PAYLOAD"
              }              
            ]      
          }
        ]
      }
    }
  }
}' "https://graph.facebook.com/v15.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Example Response

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

Best Practices

Use for messages with a consistent information hierarchy (e.g., product or article previews, weather forecasts).

Use the correct aspect ratio for your image. Photos in the generic template that aren't 1.91:1 will be scaled or cropped.

Don’t use if your message doesn't have structured information or require hierarchy.

Don't use if you need people to be able to zoom your image to full screen.

Don't use gifs in the template if you intend for them to be animated. Gifs are supported but will not be animated.

Use a carousel when there's a priority order to your content, i.e., the first item is probably the most interesting.

Strive for consistency. If one bubble has a photo, include a photo in all of them.

Minimize the number of generic templates in your carousel. Too many makes it hard for people to remember all the options.

Don't mix types of content. If you include an article next to a list of products, your experience could cause confusion.

Don't use a carousel when it's important that people see everything in the list. They may not scroll to the end. Consider a List Template instead.