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.

An Instagram user sends a message

Conversations only begin when an Instagram user sends a message to your app user through your app user's Instagram Feed, posts, story mentions, and other channels.

Instagram Inbox

An Instagram professional account has a messaging inbox that allows the user to organize messages and control message notifications however when using the API the behavior will be a little different.

General – Only after your app user to respond to a message, using your app, is the conversation moved to the General folder, regardless of the inbox settings.
Primary – All new conversations from followers will initially appear in the Primary folder.
Requests – All new conversations from Instagram users who aren't followers of your app user will appear in the Requests folder.

Learn more about the Instagram Inbox.

Inbox Limitations

Inbox folders are not supported and messages delivered by the Messenger Platform do not include folder information that is shown in the Instagram from Meta app inbox folder
Webhooks notifications or messages delivered via the API will not be considered as Read in the Instagram app inbox. Only after a reply is sent will a message be considered Read.

A webhook notification is sent

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 and their message. Your app user can use this information to respond.

Send a message

Only after an Instagram user has sent your app user's Instagram professional account a message can your app send a message to the Instagram user. Your app has 24 hours to respond to any message sent from an Instagram user to your app user.

Messages can contain the following:

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

Links
Reactions
Stickers

Templates
Text
Videos

Automated experiences

You can provide an escalation path for automated messaging experiences using one of the following:

A Single App – You can create a custom inbox to receive or reply to messages from a person. This custom inbox is powered by the same messaging app that also provides the automated experience
Multiple Apps – Handover Protocol allows you pass the conversation from one app or inbox to another. For example, one app would handle the conversation with an automated experience and, when needed, would pass the conversation to another app to continue the conversation with a human agent.

Informer les utilisateur·ices sur l’expérience automatisée

Lorsque les lois applicables l’exigent, les agents de discussion automatisée doivent informer les utilisateur·ices qu’ils ou elles interagissent avec un service automatisé :

au début de chaque conversation ou fil de discussion,
après un certain laps de temps, ou
quand une discussion avec un·e véritable agent·e est transférée à un agent virtuel.

Une attention particulière doit être portée à cette exigence lorsque les expériences de discussion automatisée sont destinées aux groupes suivants :

Marché californien et personnes basées en Californie
Marché allemand et personnes basées en Allemagne

Cette indication peut être formulée comme suit, entre autres : « Je suis le bot de [Nom de la page] », « Vous interagissez avec un service automatisé », « Vous parlez à un bot » ou « Je suis un bot de discussion automatisée ».

Même si cela n’est pas exigé par la loi, nous recommandons d’informer les utilisateur·ices lorsqu’ils ou elles interagissent avec un agent de discussion automatisée, car cela permet de gérer leurs attentes concernant leur interaction avec votre expérience de messagerie.

Consultez nos Politiques développeur pour plus d’informations.

Human agent experiences

If your app user uses a human agent to respond to messages and therefore may need more time to respond, your app can tag the response to allow your app to send the message outside the 24 hour messaging window.

You can provide an escalation path for human agent only messaging experiences with a custom inbox. Your messaging app must be able to:

receive messages sent by people and render them correctly in the custom inbox
reply to messages via the custom inbox and ensure people successfully received them

Limitations

Your app user must own any media or posts to be used in the message.
Group messaging is not supported. An Instagram professional account can only converse with one customer per conversation.
Messages in the Requests folder that have not been active for 30 days will not be returned in API calls.
Only the URL for the shared media or post is included in the webhooks notification when a customer sends a message with a share.
Your app testers must have a role on your app, grant your app access to all the required permissions, and have a role on the Instagram professional account that owns the app.

Requirements

This guide assumes you have read the Instagram Platform Overview and implemented the needed components for using this API, such as a Meta login flow 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; Some features may not work properly until your app has been granted Advanced Access

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

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