Setting Up Webhooks for Instagram

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.

Live Notifications

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:

• The app user must have granted your app appropriate Permissions (instagram_manage_insights for Stories, instagram_manage_comments for Comments and @Mentions).
• The owner of the Media object upon which the comment or @mention appears must not have set to their account to private.
• 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.
• Instagram Webhooks must be configured and appropriate Fields subscribed to in the App Dashboard.
• Your app must be in Live Mode.

Limitations

• Webhooks notifications for Comments on Albums do not include the Album ID. To get the Album ID, query the Comment ID included in the notification and request its media field.
• Webhook will not be sent if the Media upon which the comment or @mention appears was created by an account that is set to private.
• IGTV and Reels are not supported.
• Story insights metrics with counts of less than 5 will be returned as -1.

Step 1: Create an Endpoint and Configure the Webhooks Product

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.

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}
  &fields={fields}

Request Parameters

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.

Sample Request

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

Sample Response

{
  "success": true
}

Common Uses

Capturing Story Insights

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.

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

Replying to Comment @Mentions

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):

Sample Comment @Mention Payload

[
  {
    "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:

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"
}

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"
}

Replying to Caption @Mentions

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):

Sample Caption @Mention Payload

[
  {
    "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:

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"
}

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:

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"
}