Attachment Upload API Reference

The Attachment Upload API allows you to upload assets that can be sent in messages at a later time. This allows you to avoid the need to upload commonly used files multiple times. The API supports saving assets from a URL and from your local file system.

You may also use the Send API to simultaneously send a message with an attachment and save the attachment for later use. For more information, see the Send API Reference.

Upload an attachment

To upload an attachment send a POST request to the /Your-page-id/message_attachment endpoint with message.attachment with type and payload. To be able to use the asset in multiple messages, set payload.is_reusable to true.

Example request for an upload from a URL

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.

curl -X POST "https://graph.facebook.com/v19.0/Your-page-id/message_attachment" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"Your_page_access_token",
           "message":{
             "attachment":{
               "type":"image", 
               "payload":{
                 "url":"https.your-url.com/image.jp",
                 "is_reusable": true
               }
             }
           }
         }'

Example request for an upload from a file

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.

curl -X POST "https://graph.facebook.com/v19.0/Your-page-id/message_attachment" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"Your_page_access_token",
           "message":{
             "attachment":{
               "type":"image"
             }
           },
           "filedata":"@/path-to-your-file/image.png";"type":"image/png"
         }'

On success your app will receive a JSON object with attachment_id set to the ID of your attachment to be used in your messages.

{"attachment_id": "Your-attachment-ID"}

Send a message with an uploaded asset

To send a message with an asset that you have previously uploaded, uploaded with message.attachment.payload.is_reusable set to true, send a POST request to the /Your-page-id/messages endpoint with recipient.id, and the message.attachment object with type and payload.attachment_id.

Example request for an upload from a file

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.

curl -X POST "https://graph.facebook.com/v19.0/Your-page-id/messages" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"Your_page_access_token",
           "message":{
             "attachment":{
               "type":"image",
               "payload":{
                 "attachment_id":"Your-attachment-ID"
               }
             }
           }
         }'

On success your app will receive a JSON object with success set to set to true.

{"success": "true"}

Properties

For attachments from a URL, provide the follow properties in the body of the request as a JSON object. For attachments from file, send properties as form data.

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

The type of the attachment. Must be one of the following:

  • image
  • video
  • audio
  • file

payload

Object

payload object that describes the attachment.

message.attachment.payload

Property Type Description

url

String

Optional. URL of the file to upload. Max file size is 8MB for images and 25MB for all other file types (after encoding). A Timeout is set to 75 seconds for videos and 10 seconds for all other file type.

is_reusable

Boolean

Optional. Set to true to make the saved asset sendable to other message recipients. Defaults to false.

Error Codes

Error codeSubcodeMessage

100

2018074

Possible invalid ID or you do not own the attachment.

100

2018008

Failed to fetch the file from the url. Check that the URL is valid, with a valid SSL certificate, valid file size, and that the server is responding fast enough to avoid timeouts.

100

2018294

Video upload timed out or video is corrupted. Note that if the video can't be fetched within 75 seconds, it will time out

100

2018047

Upload attachment failure. A common way to trigger this error is that the provided media type does not match type of file provided int the URL