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.
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:
|
|
|
This guide assumes you have read the Instagram Platform 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:
All endpoints can be accessed via the graph.instagram.com
host.
/<IG_ID>/messages
or /me/messages
The following are required parameters for each API request:
recipient:{id:<IGSID>}
message:{<MESSAGE_ELEMENTS>}
<IG_ID>
) that received the message<IGSID>
) for the Instagram user who sent the message to your app user, received from an Instagram messaging webhook notificationinstagram_business_basic
instagram_business_manage_messages
|
|
|
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 |
The app user must own any media or posts to be used in the 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.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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>"
}
}'
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.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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>",
}
}
}
}'
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.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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>",
}
}
}
}'
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
.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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",
}
}
}'
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
.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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
}
}'
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.
Formatted for readability.
curl -X POST "https://graph.instagram.com/v21.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>",
}
}
}
}'
Learn how to send a private reply, quick reply, or template.