CAUTION: Attachment IDs expire after 90 days. After an attachment ID expires, you'll need to reupload your media to get a new attachment ID.
While reusable attachments will expire after 90 days and cannot be resent, attachments in message threads will never expire and are visible until a user deletes the message from the thread. If your use case allows, you can combine the upload and send steps as mentioned below to avoid this TTL issue.
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 Upload and send section below.
To upload an attachment send a POST
request to the /
Your-page-id
/message_attachments
endpoint with message.attachment
with type
and payload
. To be able to use the asset in multiple messages, set payload.is_reusable
to true
.
Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST "https://graph.facebook.com/v21.0
/Your-page-id/message_attachments" \
-H "Content-Type: application/json" \
-d '{
"access_token":"Your_page_access_token",
"message":{
"attachment":{
"type":"image",
"payload":{
"url":"https://your-url.com/image.jpg",
"is_reusable": true
}
}
}
}'
Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST -H "Content-Type: application/json" -d '{
"message": {
"attachment": {
"type": "image"
}
},
"filedata": "@/path-to-your-file/image.jpg",
"type": "image/png"
}' "https://graph.facebook.com/v21.0
/{PAGE_ID}/message_attachments?access_token={PAGE_ACCESS_TOKEN}"
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"}
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
.
Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "{PSID}"
},
"message": {
"attachment": {
"type": "image",
"payload": {
"attachment_id": "Your-attachment-ID"
}
}
}
}' "https://graph.facebook.com/v21.0
/{PAGE_ID}/messages?access_token={PAGE_ACCESS_TOKEN}"
On success your app will receive a JSON object with success
set to set to true
.
{"success": "true"}
You can also upload media and send it in a single API request.
CAUTION: Do not set is_public=true
in the payload for this case. Attachments in the user's message thread are always private.
Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "{PSID}"
},
"message": {
"attachment": {
"type": "image",
"payload": {
"url": "https://your-url.com/image.jpg"
}
}
}
}' "https://graph.facebook.com/v21.0
/{PAGE_ID}/messages?access_token={PAGE_ACCESS_TOKEN}"
On success your app will receive a JSON object with success
set to set to true
.
{"success": "true"}
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
Property | Type | Description |
---|---|---|
| Object | An object describing attachments to the message. |
message.attachment
Property | Type | Description |
---|---|---|
| String | The type of the attachment. Must be one of the following:
|
| Object |
|
message.attachment.payload
Property | Type | Description |
---|---|---|
| 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. |
| Boolean | Optional, defaults to false. Do not set to Set to true only when you upload and send in separate steps. Attachment IDs expire after 90 days. Reupload your media to get a new attachment ID after 90 days. While reusable attachments will expire after 90 days and cannot be resent, attachments in message threads will never expire, and are visible until a user deletes the message from the thread. |
Error code | Subcode | Message |
---|---|---|
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 |