The following content is from the Webhooks product documentation. Please refer to the Webhooks documentation if you are unfamiliar with Webhooks.
Webhooks for Instagram allows you to receive real-time notifications whenever Instagram Users comment on any of your media objects, @mention your business on other Instagram Users' media objects, or when your Stories expire.
To set up a Webhook for Instagram:
Note that unlike other Webhooks objects, the instagram
object encompasses several types of objects: media
, comment
, and story
objects.
Follow our Getting Started guide to create your endpoint and configure the Webhooks product. During configuration, make sure to choose the Instagram object and subscribe to one or more of the Instagram fields below.
Field | Description |
---|---|
| Notifies you when an Instagram User comments on a media object that you own. |
| Notifies you when an Instagram User @mentions you in a comment or caption on a media object that you do not own. |
| Notifies you when a story you own expires. |
The Page that's connected to your Instagram Business Account must install your app. To do this, your app needs to send a POST
request to the Page's /page/subscribed_apps edge using the Page's access token.
A Page access token for the Page that's connected to your Instagram Business Account, with the following permissions:
manage_pages
For example, if the Page that's connected to your Instagram Business Account had the id 134895793791914
, you could have your app send a request like this:
POST graph.facebook.com/134895793791914/subscribed_apps
{ "success": true }
If you don't want to install your app programmatically, you can easily do it with the Graph API Explorer instead:
manage_pages
permission. This will exchange your app token for a User access token with the manage_pages
permission granted.GET
dropdown menu and selecting POST
.me?fields=id,name
query with the Page's id followed by /subscribed_apps
, then submit the query. If you subscribe to the mentions
field we will send you a notification whenever a User @mentions you in a comment or caption on a media object that you do not own.
For example, here's a sample comment notification payload sent to an Instagram Business Account (17841405726653026
):
[ { "entry": [ { "changes": [ { "field": "mentions", "value": { "comment_id": "17894227972186120", "media_id": "17918195224117851" } } ], "id": "17841405726653026", "time": 1520622968 } ], "object": "instagram" } ]
To get the comment's contents, use the comment_id
property to query the /user/mentioned_comment edge:
GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120)
{ "mentioned_comment": { "timestamp": "2018-03-20T00:05:29+0000", "text": "@bluebottle challenge?", "id": "17894227972186120" }, "id": "17841405726653026" }
When you get the response, parse the payload for the text
property to determine if you want to respond to the comment. If you decide to respond, use the Webhook notification payload's media_id
property to query the /user/mentions edge:
curl -i -X POST \ -d "media_id=17918195224117851" \ -d "message=Challenge%20accepted!" \ -d "access_token=a-valid-access-token-goes-here" \ "https://graph.intern.facebook.com/17841405726653026/mentions"
{ "id": "17911496353086895" }
If you subscribe to the mentions
field we will send you a notification whenever a User @mentions you in a comment or caption on a media object that you do not own.
For example, here's a sample caption @mention notification payload sent to an Instagram Business Account (17841405726653026
):
[ { "entry": [ { "changes": [ { "field": "mentions", "value": { "media_id": "17918195224117851" } } ], "id": "17841405726653026", "time": 1520622968 } ], "object": "instagram" } ]
To get the caption's contents, use the media_id
property to query the /user/mentioned_media edge:
GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type}
{ "mentioned_media": { "caption": "@bluebottle There can be only one!", "media_type": "IMAGE", "id": "17918195224117851" }, "id": "17841405726653026" }
When you get the response, parse the payload for the caption
property to determine if you want to respond to the comment. If you decide to respond, use the Webhook notification payload's media_id
property to query the /user/mentions edge:
curl -i -X POST \ -d "media_id=17918195224117851" \ -d "message=MacLeod%20agrees!" \ -d "access_token=a-valid-access-token-goes-here" \ "https://graph.intern.facebook.com/17841405726653026/mentions"
{ "id": "17911496353086895" }