Generic Template

The generic template allows you to send a structured message that includes an image, text and buttons. A generic template with multiple templates described in the elements array will send a horizontally scrollable carousel of items, each composed of an image, text and buttons. For complete implementation details, see Generic Template.

Personalization: You may also add personalization macros to the title and subtitle fields for all formats. You can add {{first_name}}, {{last_name}}, and {{full_name}} into your title and subtitle strings to enable personalized marketing messages. For example, the title field may read as "New sale for you, {{first_name}}!". For a user named John Doe, the rendered message title will be "New sale for you, John!".

• For carousel, personalization macros may be applied to the title and subtitle field of each element in the elements field.
• Personalization is not enabled for buttons.

Request with image

You can send a template with an image if you have a link to your image, you must also set media_type to image (this is the default if not set). These links need to lead to an image file and don't have to facebook URLs.

{
  "message_id": "<MESSAGE_ID>",
  "messenger_delivery_data": {
    "subscription_token": "<SUBSCRIPTION_TOKEN>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_url":"<IMAGE_URL>",
            "subtitle":"We have the right hat for everyone.",
            "buttons":[
              {
                "type":"web_url",
                "url":"<BUTTON_URL>",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"<PAYLOAD_WEBHOOK>"
              }              
            ]      
          }
        ]
      }
    }
  }
}
  

Request with video

You can send videos in your generic template by passing in a video_id field and setting media_type to video. This video id can be retrieved from the URI when clicking on a video on facebook.

Note: For video, the video_id needs to be obtained from the Ad Videos API

{
  "message_id": "<MESSAGE_ID>",
  "messenger_delivery_data": {
    "subscription_token": "<SUBSCRIPTION_TOKEN>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "media_type": "video",
            "video_id":"<VIDEO_ID>",
            "subtitle":"We have the right hat for everyone.",
            "buttons":[
              {
                "type":"web_url",
                "url":"<BUTTON_URL>",
                "title":"View Website"
              }             
            ]     
          }
        ]
      }
    }
  }
}

Note: Currently, we do not support postback buttons in video payloads. We are actively working to add this support.

Request with multiple images

You can send a template with multiple images to showcase in a grid. You can also define one of these images as "hero" to highlight it in the grid. These links need to lead to an image files and don't have to be facebook URLs.

{
  "message_id": "<MESSAGE_ID>",
  "messenger_delivery_data": {
    "subscription_token": "<SUBSCRIPTION_TOKEN>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_urls":[
              {
                "url":"<IMAGE_URL>",
                "is_hero_image":"true"
              },
              {
                "url":"<IMAGE_URL>",
              },
            ],
            "subtitle":"We have the right hat for everyone.",
            "buttons":[
              {
                "type":"web_url",
                "url":"<BUTTON_URL>",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"<PAYLOAD_WEBHOOK>"
              }              
            ]      
          }
        ]
      }
    }
  }
}
  

• Supports upto 6 images
• Use only one of image_url or image_urls
• Only one url can be designated as the hero image using "is_hero_image":"true"

Carousel - Multiple elements

If you are trying to send a carousel, you can do so by adding multiple elements (max 10) to the payload as shown here:

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

Additional Messages

Greeting

MAPI-D supports sending a greeting pre-message before the main marketing template in freeform messages. This allows businesses to create a more conversational experience by greeting users before showing promotional content.

How to Add a Greeting

To include a greeting in your freeform message, add the text field to your generic template payload:

{
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
	"text": "Hello! Welcome to our store.",
        "elements": [...]
      }
    }
  }
}

Personalize your greetings: Include {{first_name}}, {{last_name}}, and {{full_name}} macros into your text string to enable personalized greetings for users.

Error codes

Certain errors may occur if the payload is malformed, the below table references possible error codes that may occur.