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.

Contents

• Sending Media by Attachment ID
• Sending Media by Facebook URL
  • Getting a Facebook URL
• Adding a Button
• API Response

Sending 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/v21.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Sending 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/v21.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Getting 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:

Adding 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"
}