Media Template Reference

The media template allows you to send a structured message that includes an image or video, and an optional button. For complete implementation details, see Media Template.

Contents

Request URI

https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>

Example Request

Send with Attachment ID

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/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Send with Facebook URL

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/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Example Response

{
  "recipient_id": "1254477777772919",
  "message_id": "mid.$cAAJsujCd2ORj_1qmrFdzhVa-4cvO"
}  

Properties

recipient

Description of the message recipient. All requests must include one of id, phone_number, or user_ref.

Property Type Description

recipient.id

String

PSID of the message recipient. Either PSID or phone_number must be set.

recipient.phone_number

String

Optional. Phone number of the recipient with the format +1(212)555-2368.


Your bot must be approved for Customer Matching to send messages this way.

recipient.user_ref

String

Optional. user_ref from the checkbox plugin.

recipient.name

Object

Optional. Used only if phone_number is set. Specifies the person's name in the format:


{"first_name":"John", "last_name":"Doe"}

Providing a name increases the odds of a successful match.

message

Description of the message to be sent.
Property Type Description

message.attachment

Object

An object describing attachments to the message.

message.attachment

Property Type Description

type

String

Value must be template

payload

Object

payload of the template.

message.attachment.payload

Property Name Type Description

template_type

String

Value must be media

elements

Array<element>

An array containing 1 element object that describe the media in the message. A maximum of 1 element is supported.

message.attachment.payload.elements

Property Name Type Description

media_type

String

The type of media being sent - image or video is supported.

attachment_id

String

The attachment ID of the image or video. Cannot be used if url is set.

url

String

The URL of the image. Cannot be used if attachment_id is set.

buttons

Array

An array of button objects to be appended to the template. A maximum of 1 button is supported.

Error Codes

Error CodeDescription

2018173

Failed to generate preview url

2018175

Media Preview Failed

2018182

Media Type not valid

2018183

Attachment Id is missing

2018184

Media Template Facebook Media URL Is Not Supported

2018185

Non facebook url in url param

2018186

Unable to get photo or video from facebook url

2018187

Either URL or attachment id is required

2018188

External URL is not supported