Media Template

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.

The media template can be sent via the Send API and from the Messenger webview with the Messenger Extension SDK's beginShareFlow() function.

Limitations

• Images and Video Only - The media template only supports sending images and video. Audio is currently not supported.
• Re-using Media from Facebook URLs - Attachment IDs are not supported for media from Facebook URLs. These files are already cached, and should be attached to the media template with their Facebook URL.
• Facebook URLs Only - The media template does not allow any external URL, only those on Facebook. To send an image or video with an external URL, upload it using the Attachment Upload API and get an attachment_id.

Send media by attachment ID

To send an image, send a POST request to the Send API, with the following payload property in the request body, where attachment_id is an ID generated from the attachment upload API. For requests using the attachment_id property, images and videos are supported.

For complete request property details, see Media Template Reference.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "attachment": {
      "type": "template",
      "payload": {
         "template_type": "media",
         "elements": [
            {
               "media_type": "<image|video>",
               "attachment_id": "<ATTACHMENT_ID>"
            }
         ]
      }
    }    
  }
}' "https://graph.facebook.com/v25.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Send media by Facebook URL

The media template allows lets you send videos and photos uploaded to Facebook by sending a POST request to the /messages endpoint with the Facebook URL in the url property of the request:

For complete request property details, see Media Template Reference.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "attachment": {
      "type": "template",
      "payload": {
         "template_type": "media",
         "elements": [
            {
               "media_type": "<image|video>",
               "url": "<FACEBOOK_URL>"
            }
         ]
      }
    }    
  }
}' "https://graph.facebook.com/v25.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Get the Facebook URL

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

1. Click the image or video thumbnail to open the full-size view.
2. Copy the URL from your browser's address bar.

Facebook URLs should be in the following base format:

Add a button

Optionally, buttons may also be attached to the media template. The number and types of supported buttons varies depending on whether you are using the media template with the Messenger Extensions SDKs beginShareFlow(), or sending it with the Send API:

• Send API: Up to 3 buttons of any type may be attached.
• beginShareFlow(): Only 1 button of type URL may be attached.

To add a button to your media template, add a buttons array to the template definition in the body of your request.

For more on available buttons, see Buttons.

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

API response

On success, the Messenger Platform will respond with the recipient_id and message_id of the message sent:

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