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.

Request URI

https://graph.facebook.com/v21.0/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": "AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}

Properties

`recipient`

訊息收件人的說明。所有的要求都必須包含 id、phone_number 或 user_ref。

屬性	型別	說明
`recipient.id`	字串	訊息收件人的 `PSID`、`phone_number` 或 `user_ref`。
`recipient.phone_number`	字串	選用。收件人的電話號碼（格式為 +1（212）555-2368）。您的 Bot 必須獲准使用顧客配對功能，才能透過此方式傳送訊息。
`recipient.user_ref`	字串	選用。來自核取方塊外掛程式的 `user_ref`。
`recipient.name`	物件	選用。只有設定 `phone_number` 時才會使用。以下列格式指定用戶姓名： `{"first_name":"John", "last_name":"Doe"}` 提供姓名會提高成功配對的機會。

`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`。

`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.
`sharable`	Boolean	*Optional.* Set to `true` to enable the native share button in Messenger for the template message. Defaults to `false`.

`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 3 button is supported.

Error Codes

Error Code	Description
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