Facebook Media Templates

Facebook media templates allows your business to send images, GIFs and videos as structured messages with an optional button.

Facebook Messenger supports only images and video for media templates. Audio isn't supported at the moment.

Sending a media template message with a URL button

In order to send a media template with a URL button, you can use any of the endpoints for sending messages in Conversations API with the message type facebookMediaTemplate. The example below illustrates how to send it using the endpoint POST /v1/send.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey {your-access-key}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yourcompany.com",
                  "title": "Visit website"
                }
              ],
              "media_type": "image"
            }
          ]
        }
      }
    }
  },
  "to": "4190117307726093",
  "type": "facebookMediaTemplate",
  "from": "99d0e570cd834661a1771ab08044be8b"
}'

• The message type must be facebookMediaTemplate
• The field content.facebookMediaTemplate must be set with a FacebookMessage
• The field content.facebookMediaTemplate.attachment must be set with a FacebookAttachment
• The field content.facebookMediaTemplate.attachment.type must be template for template messages
• The field content.facebookMediaTemplate.attachment.payload must be set with a FacebookAttachmentPayload
• The field content.facebookMediaTemplate.attachment.payload.template_type must be media for media template messages
• The field content.facebookMediaTemplate.attachment.payload.elements must contain at least one FacebookElement
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_type must be image for images
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_url must contain the URL of the media
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons may contain one FacebookButton
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].type may be web_url for a URL button
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].url must contain the URL the recipient will see when clicking at the button
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].title must contain the label of the button
• The field to must contain a valid Facebook-specific recipient identifier
• The field from must contain a valid Facebook channel ID

The message sent by the previous code snippet looks like the following.

The message looks like the following in Conversations API.

{
  "id": "8a7e47cf40cc472b8141ca4f033f361a",
  "conversationId": "6279c2012f7d4df393cfa1f872518518",
  "platform": "facebook",
  "to": "4190117307726093",
  "from": "101397625015964",
  "channelId": "99d0e570cd834661a1771ab08044be8b",
  "type": "facebookMediaTemplate",
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "image",
              "attachment_id": "531649808135398",
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "web_url",
                  "url": "https://www.yourcompany.com",
                  "title": "Visit website"
                }
              ]
            }
          ]
        }
      }
    }
  },
  "direction": "sent",
  "status": "sent",
  "createdDatetime": "2022-02-15T16:15:35.576027239Z",
  "updatedDatetime": "2022-02-15T16:15:35.576027239Z"
}

Sending a media template message with a call button

In order to send a media template with a call button, you can use any of the endpoints for sending messages in Conversations API with the message type facebookMediaTemplate. The example below illustrates how to send it using the endpoint POST /v1/send.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey {your-access-key}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "phone_number",
                  "payload": "+31000000000",
                  "title": "Call us!"
                }
              ],
              "media_type": "image"
            }
          ]
        }
      }
    }
  },
  "to": "4190117307726093",
  "type": "facebookMediaTemplate",
  "from": "99d0e570cd834661a1771ab08044be8b"
}'

• The message type must be facebookMediaTemplate
• The field content.facebookMediaTemplate must be set with a FacebookMessage
• The field content.facebookMediaTemplate.attachment must be set with a FacebookAttachment
• The field content.facebookMediaTemplate.attachment.type must be template for template messages
• The field content.facebookMediaTemplate.attachment.payload must be set with a FacebookAttachmentPayload
• The field content.facebookMediaTemplate.attachment.payload.template_type must be media for media template messages
• The field content.facebookMediaTemplate.attachment.payload.elements must contain at least one FacebookElement
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_type must be image for images
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_url must contain the URL of the media
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons may contain one FacebookButton
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].type may be phone_number for a call button
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].payload must contain a valid phone number which the recipient will call when clicking the button
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].title must contain the label of the button
• The field to must contain a valid Facebook-specific recipient identifier
• The field from must contain a valid Facebook channel ID

The message sent by the previous code snippet looks like the following.

The message looks like the following in Conversations API.

{
  "id": "7e57780ce09f4bada118257113bc610a",
  "conversationId": "6279c2012f7d4df393cfa1f872518518",
  "platform": "facebook",
  "to": "4190117307726093",
  "from": "101397625015964",
  "channelId": "99d0e570cd834661a1771ab08044be8b",
  "type": "facebookMediaTemplate",
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "image",
              "attachment_id": "212930650994208",
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "phone_number",
                  "title": "Call us!",
                  "payload": "+31000000000"
                }
              ]
            }
          ]
        }
      }
    }
  },
  "direction": "sent",
  "status": "sent",
  "createdDatetime": "2022-02-15T16:42:35.478886849Z",
  "updatedDatetime": "2022-02-15T16:42:35.478886849Z"
}

Sending a media template message with a custom button

In order to send a media template with a custom button, you can use any of the endpoints for sending messages in Conversations API with the message type facebookMediaTemplate. The example below illustrates how to send it using the endpoint POST /v1/send.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
     -H 'Authorization: AccessKey {your-access-key}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "postback",
                  "payload": "custom-value",
                  "title": "Click here"
                }
              ],
              "media_type": "image"
            }
          ]
        }
      }
    }
  },
  "to": "4190117307726093",
  "type": "facebookMediaTemplate",
  "from": "99d0e570cd834661a1771ab08044be8b"
}'

• The message type must be facebookMediaTemplate
• The field content.facebookMediaTemplate must be set with a FacebookMessage
• The field content.facebookMediaTemplate.attachment must be set with a FacebookAttachment
• The field content.facebookMediaTemplate.attachment.type must be template for template messages
• The field content.facebookMediaTemplate.attachment.payload must be set with a FacebookAttachmentPayload
• The field content.facebookMediaTemplate.attachment.payload.template_type must be media for media template messages
• The field content.facebookMediaTemplate.attachment.payload.elements must contain at least one FacebookElement
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_type must be image for images
• The field content.facebookMediaTemplate.attachment.payload.elements[].media_url must contain the URL of the media
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons may contain one FacebookButton
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].type may be postback for a custom button
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].payload must contain the value which will be sent as an FacebookPostback inbound message
• The field content.facebookMediaTemplate.attachment.payload.elements[].buttons[].title must contain the label of the button
• The field to must contain a valid Facebook-specific recipient identifier
• The field from must contain a valid Facebook channel ID

The message sent by the previous code snippet looks like the following.

The message looks like the following in Conversations API.

{
  "id": "5e7ce3d1058e4460ac1e801b69203d27",
  "conversationId": "6279c2012f7d4df393cfa1f872518518",
  "platform": "facebook",
  "to": "4190117307726093",
  "from": "101397625015964",
  "channelId": "99d0e570cd834661a1771ab08044be8b",
  "type": "facebookMediaTemplate",
  "content": {
    "facebookMediaTemplate": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "image",
              "attachment_id": "628162978478942",
              "media_url": "https://www.yourcompany.com/image.png",
              "buttons": [
                {
                  "type": "postback",
                  "title": "Click here",
                  "payload": "custom-value"
                }
              ]
            }
          ]
        }
      }
    }
  },
  "direction": "sent",
  "status": "sent",
  "createdDatetime": "2022-02-15T16:58:13.042419184Z",
  "updatedDatetime": "2022-02-15T16:58:13.042419184Z"
}

When the recipient clicks the button, this is how the FacebookPostback inbound message looks like in Conversations API.

{
  "id": "9fca85766f8d4940a33c28ce33e8960e",
  "conversationId": "6279c2012f7d4df393cfa1f872518518",
  "platform": "facebook",
  "to": "101397625015964",
  "from": "4190117307726093",
  "channelId": "99d0e570cd834661a1771ab08044be8b",
  "type": "facebookPostback",
  "content": {
    "facebookPostback": {
      "title": "Click here",
      "payload": "custom-value"
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-02-15T17:12:13.322Z",
  "updatedDatetime": "2022-02-15T17:12:13.322Z"
}

Note that the FacebookPostback inbound message contains the button label in content.facebookPostback.title and the custom value set in the content.facebookPostback.payload.