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 someone comments on your app users' Media objects, @mentions your app users, or when your app users' Stories expire.
In order to receive live Webhooks notifications (i.e., notifications generated by user activity instead of by the App Dashboard's Test buttons), all of the following conditions must be met:
media
field.-1
.Follow our Getting Started guide to create an endpoint that can accept and process Webhooks notifications and configure the Webhooks product using the App Dashboard (configuration via the App Subscriptions edge is not supported). During configuration, make sure to choose the Instagram object and subscribe to one or more Instagram Fields.
Field | Description | Permissions |
---|---|---|
Notifies your endpoint when someone comments on a media object owned by an Instagram Professional user who has granted your app appropriate permissions. | instagram_manage_comments, | |
Notifies your endpoint when an someone @mentions in a comment or caption an Instagram Professional user who has granted your app appropriate permissions. | instagram_manage_comments, | |
Notifes your endpoint when a story owned by an Instagram Professional user who has granted your app appropriate permissions expires. | instagram_manage_insights, |
Your app must enable Page subscriptions on the Page connected to the app user's account by sending a POST
request to the Page Subscribed Apps edge and subscribing to any Page Field.
POST /{page-id}/subscribed_apps ?access_token={access-token} &fields={fields}
Value Placeholder | Value Description |
---|---|
| ID of the Page connected to the app user's account. |
| The app user's Page Access Token. |
| A Page Field (e.g, |
Technically it doesn't matter which Page Field you subscribe to. Your app will not receive notifications of changes to that field unless you configure Page subscriptions in the App Dashboard and subscribe to that field.
curl -i -X POST \
"https://graph.facebook.com/v10.0
/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."
{ "success": true }
If you subscribe to the story_insights
field, we will send your endpoint a notification containing Story insights metrics whenever an Instagram Business or Creator Account's story expires.
[ { "entry": [ { "changes": [ { "field": "story_insights", "value": { "media_id": "18023345989012587", "exits": 1, "replies": 0, "reach": 17, "taps_forward": 12, "taps_back": 0, "impressions": 28 } } ], "id": "17841405309211844", // Instagram Business or Creator Account ID "time": 1547687043 } ], "object": "instagram" } ]
If you subscribe to the mentions
field we will send your endpoint a notification whenever an Instagram user @mentions an Instagram Business or Creator Account in a comment or caption.
For example, here's a sample comment notification payload sent for 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 GET /{ig-user-id}/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. To respond, use the Webhook notification payload's caption_id
and media_id
property values to query the POST /{ig-user-id}/mentions
endpoint:
curl -i -X POST \ -d "comment_id=17894227972186120" \ -d "media_id=17918195224117851" \ -d "message=Challenge%20accepted!" \ -d "access_token={access-token}" \ "https://graph.facebook.com/17841405726653026/mentions"
{ "id": "17911496353086895" }
If you subscribe to the mentions
field we will send your endpoint a notification whenever a User @mentions an Instagram Business or Creator Account in a comment or caption on a media object not owned by the Business or Creator.
For example, here's a sample caption @mention notification payload sent for 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 GET /{ig-user-id}/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. To respond, use the Webhook notification payload's media_id
property to query the POST /{ig-user-id}/mentions
edge:
curl -i -X POST \ -d "media_id=17918195224117851" \ -d "message=MacLeod%20agrees!" \ -d "access_token={access-token}" \ "https://graph.facebook.com/17841405726653026/mentions"
{ "id": "17911496353086895" }