Webhooks for Instagram

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:

1. Set up your endpoint and configure the Webhooks product.
2. Install your app using the Facebook Page that's connected to your Business Account.

Note that unlike other Webhooks objects, 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 webhook and request the media field.

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

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-id}/subscribed_apps edge using the Page's access token.

Permissions

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:

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 you a notification containing Story insights metrics whenever the 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 User ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

Replying to Comment @Mentions

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

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 /user/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. If you decide to respond, use the Webhook notification payload's media_id property to query the /user/mentions edge:

Sample Query

curl -i -X POST \
 -d "media_id=17918195224117851" \
 -d "message=Challenge%20accepted!" \
 -d "access_token=a-valid-access-token-goes-here" \
 "https://graph.facebook.com/17841405726653026/mentions"

Sample Response

{
  "id": "17911496353086895"
}

Replying to Caption @Mentions

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

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 /user/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. If you decide to respond, use the Webhook notification payload's media_id property to query the /user/mentions edge:

Sample Query

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

Sample Response

{
  "id": "17911496353086895"
}