미디어 템플릿

미디어 템플릿을 사용하면 선택적 버튼을 통해 이미지, GIF, 동영상을 구조화된 메시지로 보낼 수 있습니다. 미디어 템플릿으로 보낸 동영상과 애니메이션 GIF는 대화 내에서 재생됩니다.

미디어 템플릿은 보내기 API를 통해 보내거나 Messenger 확장 기능 SDK의 beginShareFlow() 기능을 사용하여 Messenger WebView에서 보낼 수 있습니다.

이미지 및 동영상 전용

현재 미디어 템플릿에서는 이미지 및 동영상 전송 기능만 이용할 수 있으며, 오디오는 아직 지원되지 않습니다.

첨부 파일 ID를 사용하여 미디어 보내기

이미지를 보내려면 요청 본문에 다음 payload 속성을 포함하여 보내기 API에 POST 요청을 보냅니다. attachment_id는 첨부 파일 업로드 API에서 생성된 ID입니다. attachment_id 속성을 사용한 요청에는 이미지 및 동영상이 지원됩니다.

요청 속성에 대한 자세한 정보는 미디어 템플릿 참조를 확인하세요.

Facebook URL의 미디어 다시 사용하기

첨부 파일 ID는 Facebook URL의 미디어를 지원하지 않습니다. 이러한 파일은 이미 캐시되어 있으며 해당 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>",
               "attachment_id": "<ATTACHMENT_ID>"
            }
         ]
      }
    }    
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Facebook URL을 사용하여 미디어 보내기

미디어 템플릿을 사용하면 요청의 url 속성에 Facebook URL이 포함된 POST 요청을 /messages 엔드포인트로 전송하여 Facebook에 업로드된 동영상과 사진을 보낼 수 있습니다.

요청 속성에 대한 자세한 정보는 미디어 템플릿 참조를 확인하세요.

Facebook URL 전용

미디어 템플릿에서는 Facebook의 URL만 허용되며 외부 URL은 허용되지 않습니다. 이미지 또는 동영상을 외부 URL을 통해 보내려면 첨부 업로드 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 URL 받기

이미지 또는 동영상에 대한 Facebook URL을 받으려면 다음 단계를 따르세요.

이미지 또는 동영상 썸네일을 클릭하여 전체 화면 크기로 엽니다.
브라우저의 주소창에서 URL을 복사합니다.

Facebook URL은 다음 기본 형식으로 구성되어야 합니다.

미디어 유형	미디어 출처	URL 형식
동영상	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(): URL 유형의 버튼을 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"
}