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/v18.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/v18.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/v18.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

message.attachment

message.attachment.payload

Error Codes