Upload Media for Instagram Messaging

This document shows you how to upload media to the Meta servers using the Attachment Upload API. This media can then be used in Instagram messages.

Note: You can upload and send an attachment in a single API call.

Before You Start

You need the following:

• The Page ID for the Facebook Page linked to the Instagram for the business who owns the media to be uploaded
• A Page access token requested by a person who can perform the MESSAGING task on the Page
• Your app will need approval from the person uploading the media via Business Login for Instagram or Facebook Login for the following permissions:
  • instagram_basic
  • instagram_manage_comments
  • instagram_manage_messages
  • pages_messaging
• Your app will need Advanced Access for the required permissions to upload media for Pages you do not own or administer
• Either the URL for the media, if uploading from a URL, or the file path to the media, if uploading from your server
  • Media types can be image (which include GIFs), video, or audio
  • Media formats can be:

Limitations

• If your app only has Standard Access to any of the required permissions, your app will only be able to upload media for Pages you own or administer.
• The permissions listed above when granted to your app allows your app to upload media but does not allow your app to send a message.
• Only audio and video files can be uploaded from a server. Images must be uploaded from a URL.

Upload Media from a URL

You can upload audio files, images, and videos from a URL.

To upload media from a URL, you can send a POST request to the /PAGE-ID/message_attachments endpoint with the platform set as Instagram and the message attachment type set to the type of media you are uploading, audio, image, or video. Add the URL and is_reusable in the payload. Set is_reusable to true so that the media can be used in multiple messages.

Note: All keys within the message object, such as attachment, type, and payload are strings.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/message_attachments
    ?message={
      "attachment":
          {
          "type": "MEDIA-TYPE",
          "payload":
              {
                  "url": "URL",
                  "is_reusable": "true",
              },
          }
    }
    &platform=instagram
    &access_token=PAGE-ACCESS-TOKEN"

Upon success, your app will receive an ID for the attachment. You can now include this ID in your messages.

{
    "attachment_id": "ATTACHMENT-ID"
}

Upload Media from a Server

You can upload audio files and videos from a server. Images must be uploaded from a URL.

To upload media from a server, you can send a POST request to the /PAGE-ID/message_attachments endpoint with the message attachment payload containing the URL and the platform set as Instagram. If you want to use the media in multiple messages, include the is_reusable set to true in the payload.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/message_attachments
    &platform=instagram
    &message={'attachment':{'type':'MEDIA-TYPE-AUDIO-OR-VIDEO','is_reusable':'true'}}
    &filedata=FILE-PATH;type=PATH-TYPE
    ?access_token=PAGE-ACCESS-TOKEN"

Upon success, your app will receive an ID for the attachment. You can now include this ID in your messages.

{
    "attachment_id": "ATTACHMENT-ID"
}

Send a Media Message

Now that you have uploaded media, you can send it in a message.

To send a message that contains the media you uploaded, send a POST request to the /PAGE-ID/messages endpoint with the recipient parameter containing the Instagram-scoped ID (IGSID) and the message parameter containing an attachment object with the type set to MEDIA_SHARE and payload.id set to the attachment ID.

Your business must own the media to be used in the message.

Sample Request

curl -i -X POST "https://graph.facebook.com/v21.0/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={
      attachment: 
        {
          type:MEDIA_SHARE, 
          payload:{attachment_id:ATTACHMENT-ID}
        }
      }
  &access_token=PAGE-ACCESS-TOKEN"  

Sample API Response

Upon success, your app will receive the following JSON response:

{
  "recipient_id": "IGSID",
  "message_id": "MESSAGE-ID"
}

Upload and Send

You can also upload media and send it in a single API request.

From a URL

To upload and send media in one request, send a POST request to the /PAGE-ID/messages endpoint with the recipient parameter containing the Instagram-scoped ID (IGSID) and the message parameter containing an attachment object with the type set to audio, image, or video and payload containing the URL and is_reusable set to true.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={
      'attachment': 
        {
          'type':'video', 
          'payload':{'url':'https://you-video-url.mp4'},
          'is_reusable': 'true',
        }
      }
  &access_token=PAGE-ACCESS-TOKEN"  

Sample API Response

Upon success, your app will receive the following JSON response:

{
  "recipient_id": "IGSID",
  "message_id": "MESSAGE-ID",
  "attachment_id": "ATTACHMENT-ID"
}

From a Server

To upload and send a audio or video from your server, send a POST request to the /PAGE-ID/messages endpoint with the recipient parameter containing the Instagram-scoped ID (IGSID) and the message parameter containing an attachment object with the type set to AUDIO or VIDEO and filedata parameter the file's location and type. The format for filedata values looks like @/path_on_my_server/video.mp4;type=video/mp4.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={
      'attachment': 
        {
          'type':'MEDIA-TYPE-AUDIO-OR-VIDEO'
          'is_reusable':'true'
        }       
      }
  &'filedata':'FILE-PATH;type=PATH-TYPE'
  &access_token=PAGE-ACCESS-TOKEN"  

Sample API Response

Upon success, your app will receive the following JSON response:

{
  "recipient_id": "IGSID",
  "message_id": "MESSAGE-ID",
  "attachment_id": "ATTACHMENT-ID"
}