Saving Assets

To optimize sending assets, you may optionally have the Messenger Platform save an asset when it is sent. This is useful if you plan on sending the same attachments repeatedly, since it eliminates the need to upload an asset with each request.

The Messenger Platform offers two APIs that allow you to save assets for later use: the Send API, and the Attachment Upload API. Both APIs support saving assets from URL and from your local file system.

Contents

Supported Asset Types

The Messenger Platform supports saving the following asset types, up to 25MB in size:

  • image
  • audio - Content-Type header must use type audio. For example, audio/mp3.
  • video
  • file

Saving with the Send API

The Send API allows you to save an asset that is sent with a message, as an alternative to uploading it in advance with the Attachment Upload API. To do this, send a POST request with payload.is_reusable set to true to the /messages endpoint.

Saving from URL

To save an asset from a URL, specify the source URL in the payload.url property of the attachment object of your message:

{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "attachment":{
      "type":"<ASSET_TYPE>", 
      "payload":{
        "url":"<ASSET_URL>",
        "is_reusable": true
      }
    }
  }
}

For a complete list of API calls and request properties, see the Send API Reference.

Saving from File

To save an asset from your local file system, submit your message request to the Send API as form data, and specify the file location in the filedata field of the request:

curl  \
  -F 'recipient={"id":"<PSID>"}' \
  -F 'message={"attachment":{"type":"<ASSET_TYPE>", "payload":{"is_reusable"=true}}}' \
  -F 'filedata=@/tmp/shirt.png;type=image/png' \
  "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

For a complete list of API calls and request properties, see the Send API Reference.

API Response

The response will contain an attachment_id that can be used to attach the asset to future messages. Please note that this ID is private and only the page that originally sent the attachment can reuse it.

{
  "recipient_id": "1254444444682919",
  "message_id": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P",
  "attachment_id": "687799999980546"
}

Saving with the Attachment Upload API

The Attachment Upload API allows you to upload assets in advance. This is useful if you know in advance that you will need to send particular assets repeatedly. To do this, send a POST request to the /message_attachments endpoint.

For a complete list of API calls and request properties, see the Attachment Upload API Reference.

Saving from URL

To save an asset from a URL, specify the source URL in the payload.url property of the attachment object of your message:

curl -X POST -H "Content-Type: application/json" -d '{
  "message":{
    "attachment":{
      "type":"image", 
      "payload":{
        "is_reusable": true,
        "url":"http://www.messenger-rocks.com/image.jpg"
      }
    }
  }
}' "https://graph.facebook.com/v2.6/me/message_attachments?access_token=<PAGE_ACCESS_TOKEN>"

For a complete list of API calls and request properties, see the Attachment Upload API Reference.

Saving from File

To save an asset from your local file system, submit your message request to the Attachment Upload API as form data, and specify the file location in the filedata field of the request:

curl  \
  -F 'recipient={"id":"<PSID>"}' \
  -F 'message={"attachment":{"type":"<ASSET_TYPE>", "payload":{"is_reusable"=true}}}' \
  -F 'filedata=@/tmp/shirt.png;type=image/png' \
  "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

For a complete list of API calls and request properties, see the Attachment Upload API Reference.

API Response

The response will contain an attachment_id that can be used to attach the asset to future messages. Please note that this ID is private and only the page that originally sent the attachment can reuse it.

{
  "attachment_id":"1857777774821032"
}

Sending Saved Assets

Once you have an attachment_id for your saved asset, you can use it to attach the asset to a message. For more information, see Sending Messages - Attaching Saved Assets.