Set Up Webhooks for Instagram

Webhooks for Instagram allow you to receive real-time notifications whenever someone comments on the Media objects of your app users; @mentions your app users; or when Stories of your app users expire.

Receive Live Webhook Notifications

To receive live webhook notifications, the following conditions must be satisfied:

• Your app must have Instagram webhooks configured and appropriate fields subscribed to in the App Dashboard.
• For Consumer apps, they must be in Live Mode.
• For Business apps, they must have permissions with an Advanced Access level. You can request Advanced Access for permissions as shown here:

• The app user must have granted your app appropriate permissions (instagram_manage_insights for Stories, instagram_manage_comments for Comments and @Mentions).
• The Page connected to the app user's account must have Page subscriptions enabled.
• The Business connected to the app user's Page must be verified.
• The owner of the Media object upon which the comment or @mention appears must not have set their account to private.

Limitations

• Webhook notifications for Comments on albums don't include the album ID. Get the album ID by querying the Comment ID in the webhook and request its media field.
• Apps don't receive a webhook notifications if the Media where the comment or @mention appears was created by a private account.
• Story insights metrics with counts of less than 5 are returned as -1.
• Apps only receive webhook notifications for comments on live IG Media if the media is on broadcast.
• Reels are not supported.
• Your app must have successfully completed App Review (advanced access) to receive webhooks notifications for comments and live_comments webhooks fields.
• If the media is used for dynamic ads, the ad ID will not be returned.

Step 1: Create an Endpoint

Create an endpoint that accepts and processes webhooks. During the configuration, select the Instagram Graph API object, click Set up, and subscribe to one or more Instagram fields.

Instagram Fields

Step 2: Enable Page Subscriptions

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.

Endpoint Requirements

• the app user's Page Access Token
• pages_manage_metadata

Request Syntax

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

Request Parameters

Your app does not receive notifications for changes to a field unless you configure Page subscriptions in the App Dashboard and subscribe to that field.

Sample Request

curl -i -X POST \
  "https://graph.facebook.com/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Sample Response

{
  "success": true
}

Common Uses

Capture Story Insights

If you subscribe to the story_insights field, we send your endpoint a webhook notification containing user interaction metrics on a story, after the story has expired.

Sample Story Insights Payload

[
  {
    "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"
  }
]

Reply to Comment @Mentions

If you subscribe to the mentions field, we send your endpoint a webhook notification whenever an Instagram user @mentions an Instagram Business or Creator Account in a comment or caption.

For example, here's a sample comment webhook notification payload sent for an Instagram Business Account (17841405726653026):

Sample Comment @Mention Payload

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Get the Comment's Contents

To get the comment's contents, use the comment_id property to query the GET /{ig-user-id}/mentioned_comment edge:

Sample Query

GET https://graph.facebook.com/17841405726653026
  ?fields=mentioned_comment.comment_id(17894227972186120)

Sample Response

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

Parse the Payload and Respond

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:

Sample Query

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"

Sample Response

{
  "id": "17911496353086895"
}

Reply to Caption @Mentions

If you subscribe to the mentions field, we send your endpoint a webhook 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 webhook notification sent for an Instagram Business Account (17841405726653026):

Sample Caption @Mention Webhook Notification

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

Get the Caption's Contents

To get the caption's contents, use the media_id property to query the GET /{ig-user-id}/mentioned_media edge:

Sample Query

GET https://graph.facebook.com/17841405726653026
  ?fields=mentioned_media.media_id(17918195224117851){caption,media_type}

Sample Response

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

Parse the Payload and Respond

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 media_id property to query the POST /{ig-user-id}/mentions edge:

Sample Query

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Sample Response

{
  "id": "17911496353086895"
}