Send Messages

This guide shows you how to send a message to an Instagram user from your Instagram professional account using the Instagram API with Instagram Login.

How It Works

The Instagram API with Instagram Login enables your app users to send and receive messages between their Instagram professional account and their customers, potential customers, and followers. Conversations can begin through their Instagram Feed, posts, story mentions, and other channels. When an Instagram user sends a message to your app user, an event is triggered, and a webhook notification is sent to your webhook server. The notification contains the Instagram user's Instagram-scoped ID (IGSID) and their message. Your app user can use this information to respond.

Messages can contain the following:

Audio files
GIFs
Images
Instagram posts (owned by your app user)

Links
Reactions
Stickers

Templates
Text
Videos

Requirements

This guide assumes you have read the Instagram API Overview and implemented the needed components for using this API, such as Instagram Login for Business to receive Instagram User access tokens and a webhooks server to receive notifications.

You will need the following:

Access Level

Advanced Access if your app serves Instagram professional accounts you don't own or manage
Standard Access if your app serves Instagram professional accounts you own or manage or have added to your app in the App Dashboard

Access tokens

An Instagram User access token requested from a person who can send a message from the Instagram professional account

Base URL

All endpoints can be accessed via the graph.instagram.com host.

Endpoints

/<IG_ID>/messages or /me/messages

Required Parameters

The following are required parameters for each API request:

recipient:{id:<IGSID>}
message:{<MESSAGE_ELEMENTS>}

IDs

The app user's Instagram professional account ID (<IG_ID>) that received the message
The Instagram-scoped ID (<IGSID>) for the Instagram user who sent the message to your app user, received from an Instagram messaging webhook notification

Permissions

instagram_business_basic
instagram_business_manage_messages

Webhook event subscriptions

messages
messaging_optins

messaging_postbacks
messaging_reactions

messaging_referrals
messaging_seen

Media types and specifications

Media Type	Supported Format	Supported Size Maximum
Audio	aac, m4a, wav, mp4	25MB
Image	png, jpeg, gif	8MB
Video	mp4, ogg, avi, mov, webm	25MB

Limitations

The app user must own any media or posts to be used in the message.

Send a text message

To send a message that contains text or a link, send a POST request to the /<IG_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 -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "message:{
              "text":"<TEXT_OR_LINK>"
           }
        }'

Send an image or GIF

To send an image or gif, send a POST request to the /<IG_ID>/messages endpoint with the recipient parameter containing the Instagram-scoped ID (<IGSID>) and the message parameter containing an attachment object with type set to image and payload containing url set to the URL for the image or GIF.

Sample Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "message:{
              "attachment":{
               "type":"image",
               "payload":{
                 "url":"<IMAGE_OR_GIF_URL>",
               }
             }
           }
         }'

Send audio or video

To send an audio message, send a POST request to the /<IG_ID>/messages endpoint with the recipient parameter containing the Instagram-scoped ID (<IGSID>) and the message parameter containing the attachment object with type as audio or video and payload containing url set to the URL for the audio or video file.

Sample Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "message:{
              "attachment":{
               "type":"audio",  // Or set to video 
               "payload":{
                 "url":"<AUDIO_OR_VIDEO_FILE_URL>",
               }
             }
          }
        }'

Send a Sticker

To send a heart sticker, send a POST request to the /<IG_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 -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "message:{
              "attachment":{
                "type":"like_heart",
              }
            }
         }'

React or unreact to a message

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

To remove a reaction, repeat this request with the sender_action parameter to unreact with the payload containing message_id parameter only. Omit reaction.

Sample Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "sender_action":"react",  // Or set to unreact to remove the reaction
           "payload":{
             "message_id":"<MESSAGE_ID>",
             "reaction":"love",      // Omit if removing a reaction
           }
         }'

Send a Published Post

To send a message that contains an app user's Instagram post, send a POST request to the /<IG_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.

The app user must own the post to be used in the message. Learn how to get your app user's Instagram posts.

Learn how to fetch the media owned by the business.

Sample Request

Formatted for readability.

curl -X POST "https://graph.instagram.com/v20.0/<IG_ID>/messages"
     -H "Authorization: Bearer <INSTAGRAM_USER_ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d '{
           "recipient":{
               "id":"<IGSID>"
           },
           "message:{
              "attachment":{
                "type":"MEDIA_SHARE",
                "payload":{
                  "id":"<POST_ID>",
                }
              }
           }
        }'

Next Steps

Learn how to send a private reply, quick reply, or template.