Media Template

Updated: Oct 23, 2025

The media template allows you to send images, GIFs, and video as a structured message with an optional button. Videos and animated GIFs sent with the media template are playable in the conversation.

For media templates you must either:

Use an attachment

Get a Facebook URL for an image or video

Sending a media template with an attachment

To send a message with an attachment you must first upload your image/video using the attachment upload api. After successfully uploading an attachment that contains your image/video you should receive an attachment_id, record that and use in the payload below.

{
  "message_id": "<MESSAGE_ID>",
  "messenger_delivery_data": {
    "subscription_token": "<SUBSCRIPTION_TOKEN>"
  },
  "message":{
    "attachment": {
      "type": "template",
      "payload": {
         "template_type": "media",
         "elements": [
            {
               "media_type": "image",
               "attachment_id": "<ATTACHMENT_ID>"
            }
         ]
      }
    }
  }
}

Sending a media template with a URL

To get the Facebook URL for an image or video, do the following:

Click the image or video thumbnail to open the full-size view.

Copy the URL from your browser’s address bar. Facebook URLs should be in the following base format:

Media Type	Media Source	URL Format
Video	Facebook Page	`https://business.facebook.com/PAGE_NAME/videos/NUMERIC_ID`
Video	Facebook Account	`https://www.facebook.com/USERNAME/videos/NUMERIC_ID`
Image	Facebook Page	`https://business.facebook.com/PAGE_NAME/photos/NUMERIC_ID`
Image	Facebook Account	`https://www.facebook.com/photo.php?fbid=NUMERIC_ID`

After retrieving a valid facebook URL you can use it in the below payload.

{
  "message_id": "<MESSAGE_ID>",
  "messenger_delivery_data": {
    "subscription_token": "<SUBSCRIPTION_TOKEN>"
  },
  "message":{
    "attachment": {
      "type": "template",
      "payload": {
         "template_type": "media",
         "elements": [
            {
               "media_type": "image",
               "url": "<FACEBOOK_URL>"
            }
         ]
      }
    }
  }
}

Adding a button

Optionally, buttons may also be attached to the media template. You can add up to 3 buttons to a media template message, similar to generic template.

    "elements": [
   {
      "media_type": "image",
      "url": "<MEDIA_URL>",
      "buttons": [
         {
            "type": "web_url",
            "url": "<WEB_URL>",
            "title": "View Website",
         }
      ]
   }
]