Webhooks for Instagram

Webhooks for Instagram allows you to receive real-time notifications whenever Instagram users comment on any of an Instagram Business or Creator Account's media objects, @mention a Business or Creator on other Instagram users' media objects, or when a Business or Creator's stories expire.

To set up a Webhook for Instagram:

1. Set up your endpoint and configure the Webhooks product.
2. Install your app using a Facebook account that's connected to the Business or Creator Account for which you are setting up Webhooks.

Once setup, you will receive Webhooks notifications for that account and any other Business or Creator Accounts that use your app.

Note that unlike other Webhooks objects that typically map to a single object, the instagram object encompasses several types of objects: media, comment, and story objects.

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 the media field.

Permissions

In order to receive Webhooks notifications while your app is in Live mode, app users must grant your app the instagram_manage_insights permission.

Setting Up Your Endpoint and Webhook Product

Follow our Getting Started guide to create your endpoint and configure the Webhooks product using your app's dashboard (configuration via the /{app-id}/subscriptions edge is currently unsupported). During configuration, make sure to choose the Instagram object and subscribe to one or more of the Instagram fields below.

Installing Your App

Your app must be installed on the Facebook Page that's connected to the Instagram Business or Creator Account. To do this, your app needs to send a POST request to the Page's /{page-id}/subscribed_apps edge using the Page's access token.

Permissions

A Page access token for the Page connected to the Instagram Business or Creator Account, with the following permissions:

• manage_pages

For example, if the Page connected to the Instagram Business Account has the ID 134895793791914, you could send the following request:

Sample Request

POST graph.facebook.com/3.1/134895793791914/subscribed_apps

Sample Response

{
  "success": true
}

Graph API Explorer

If you don't want to install your app programmatically, you can easily do it with the Graph API Explorer instead:

1. Select your app in the Application dropdown menu. This will return your app's access token.
2. Click the version dropdown and change it from 3.2 to 3.1 or older.
3. Click the Get Token dropdown and select Get User Access Token, then choose the manage_pages permission. This will exchange your app token for a User access token with the manage_pages permission granted.
4. Click Get Token again and select your Page. This will exchange your User access token for a Page access token.
5. Change the operation method by clicking the GET dropdown menu and selecting POST.
6. Replace the default me?fields=id,name query with the Page's id followed by /subscribed_apps, then submit the query.

Common Uses

• Replying to comment @mentions
• Replying to caption @mentions
• Capturing Story Insights

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 on a media object not owned by the Business or Creator.

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