媒体模板

媒体模板让您可以通过结构化消息的形式发送图片、GIF 和视频，并可选择在其中添加按钮。利用这种方式发送的视频和 GIF 动图可在对话中播放。

媒体模板既可以通过发送 API 发送，也可以使用 Messenger 功能插件 SDK 的 beginShareFlow() 参数从 Messenger webview 中发送。

仅支持图片和视频

当前，媒体模板仅支持发送图片和视频，暂不支持发送音频。

通过附件编号发送媒体

要发送图片，向发送 API 发送 POST 请求，并在请求正文中包含以下 payload 属性，其中 attachment_id 是指从附件上传 API 生成的编号。如请求使用 attachment_id 属性，则支持发送图片和视频。

如需了解完整的请求属性详情，请查阅媒体模板参考文档。

重复使用来自 Facebook 网址的媒体

来源为 Facebook 网址的媒体不支持使用附件编号。这些媒体文件已被缓存，应通过 Facebook 网址附加至媒体模板。

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

通过 Facebook 网址发送媒体

媒体模板允许您通过向 /messages 端点发送 POST 请求，并在请求的 url 属性中包含 Facebook 网址，来发送已上传至 Facebook 的视频和照片：

如需了解完整的请求属性详情，请查阅媒体模板参考文档。

仅支持 Facebook 网址

媒体模板不允许使用除 Facebook 网址以外的任何外部网址。如要发送来自外部网址的图片或视频，请使用附件上传 API 上传该图片或视频，并获取 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>",
               "url": "<FACEBOOK_URL>"
            }
         ]
      }
    }    
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

获取 Facebook 网址

要获取图片或视频的 Facebook 网址，请执行以下操作：

点击图片或视频缩略图以打开原始尺寸的视图。
从浏览器的地址栏复制网址。

Facebook 网址的基本格式如下：

媒体类型	媒体来源	网址格式
视频	Facebook 主页	`https://business.facebook.com/<PAGE_NAME>/videos/<NUMERIC_ID>`
视频	Facebook 帐户	`https://www.facebook.com/<USERNAME>/videos/<NUMERIC_ID>/`
图片	Facebook 主页	`https://business.facebook.com/<PAGE_NAME>/photos/<NUMERIC_ID>`
图片	Facebook 帐户	`https://www.facebook.com/photo.php?fbid=<NUMERIC_ID>`

添加按钮

您也可以视需要在媒体模板中附加按钮。根据您是通过 Messenger 功能插件 SDK 的 beginShareFlow() 参数使用媒体模板，还是通过发送 API 来发送媒体模板，所支持的按钮数量和类型有所不同，具体如下：

Send API：可附加不超过 3 个任意类型的按钮。
beginShareFlow()：仅可附加 1 个网址类型的按钮。

要向媒体模板添加按钮，在请求正文的模板定义中添加 buttons 数组即可。

如需详细了解可用按钮，请参阅按钮。

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

API 响应

一旦发送成功，Messenger 平台会返回所发送消息的 recipient_id 和 message_id：

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