Freeform Messaging Types for Instagram Messaging

This document contains the requirements for sending freeform messages from your Instagram Business account to your customers using the Messenger Platform from Meta.

You can send a freeform message that contains:

  • an image, video, or audio
  • a reaction or sticker
  • text, including a link

Before You Start

This guide assumes you have read the Messenger Platform Overview and implemented the needed components such as a Facebook Page linked your Instagram Business account (or test Page), registered as a Meta developer, and created a Business App ID with the Messenger > Instagram Messaging product in the App Dashboard.

You may also want to check the status of the Meta Developer Platform to ensure there are no issues.

Requirements

  • The ID for the Facebook Page linked to your Instagram Business account
  • The Instagram-scoped ID for customer who sent your business a message
  • A Page access token requested from a person who can perform the MESSAGE task on the Facebook Page linked to your Instagram Business account
  • The instagram_manage_messages permission
  • An escalation path to a human agent. Experiences can start from an automated flow to qualify intent but must have a way for customers to chat with a human agent as needed.
    • All messages sent by a human agent outside of the 24-hour messaging window must include the HUMAN_AGENT tag.
Media TypeSupported FormatSupported Size Maximum

Audio

acc, m4a, wav, mp4

25MB

Image

png, jpeg

8MB

Video

mp4, ogg, avi, mov, webm

25MB

Limitations

  • Apps with Standard Access can only send messages to people that have a role on the app
  • An image can only be sent through URLs

Send a Text or Link

To send a message that contains text or a link, 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 the text or link.

Message text must be UTF-8 and be a 1000 bytes or less. Links must be valid formatted URLs.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={text: TEXT-OR-LINK}
  &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"
}

Send Audio, Image or Video

You can send an audio message or a video that you have either uploaded to a Meta server or sent from your server.

Send a Published Post

To send a message that contains a post you published to Instagram, 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 containing the Meta ID for the post.

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

Sample Request

curl -i -X POST "https://graph.facebook.com/v15.0/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={
      attachment: 
        {
          type:MEDIA_SHARE, 
          payload:{id:POST-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"
}

Send a Media Asset from a URL

To send a URL containing a audio, image, or video, 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.

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',    // 'audio' or 'image'
          'payload':{'url':'https://you-video-url.mp4'}
        }
      }
  &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"
}

Send a Media Asset from Your Server

To 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.

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'    // 'audio'
        }       
      }
  'filedata':'@/path/video.mp4;type=video/mp4'
  &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"
}

Send a Sticker

To send a heart sticker, 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 like_heart.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/v15.0/PAGE-ID/messages
  ?recipient={id: IGSID}
  &message={
      attachment: 
        {
          type: like_heart
        }
      }
  &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"
}

React to a Message

To send a reaction, send a POST request to the /PAGE-ID/messages endpoint with the recipient parameter containing the Instagram-scoped ID (IGSID) and the sender_action parameter to react with the payload containing the message_id set to the ID for the message to apply the reaction to and reaction to love.

Sample Request

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/v15.0/PAGE-ID/messages
  ?recipient={id: IGSID}
  &sender_action=react
  &payload={
      message_id:MESSAGE-ID,
      reaction:love
      }
  &access_token=PAGE-ACCESS-TOKEN"  

To remove a reaction from a message, send a POST request to the /PAGE-ID/messages endpoint with the recipient parameter containing the Instagram-scoped ID (IGSID) and the sender_action parameter to unreact with the payload containing the message_id set to the ID for the message from which to remove the reaction.

Sample Request

curl -i -X POST "https://graph.facebook.com/v15.0/PAGE-ID/messages
  ?recipient={id: IGSID}
  &sender_action=unreact
  &payload={
      message_id:MESSAGE-ID 
      }
  &access_token=PAGE-ACCESS-TOKEN"  

Sample Response

Upon success, your app will receive the following JSON response for react and unreact requests:

{
  "recipient_id": "IGSID"
}

Next Steps

See Also

Developer Support