Instagram on Facebook

Introduction

Since the new Instagram API is implemented as part of Facebook’s Graph API, we built the integration with the new API by adding several new resource types and options to our existing Managed Sources for Facebook Pages.

Prerequisites

To use instagram features you must have an Instagram Business Account. Any Instagram account can become an Instagram Business Account: https://business.instagram.com/blog/creating-a-business-profile-on-instagram/.

To use Managed Sources for Instagram on Facebook's Graph API you will need:

  • An Instagram Business Account
  • A Facebook Page with:
    • Your Instagram Business Account connected to your Page.
  • A Facebook User Access Token with:
    • The Page Public Content Access feature or the manage_page permission
    • The instagram_basic permission
    • The instagram_manage_comments permission
    • Optional: only for content that has tagged your business
    • The instagram_manage_insights permission
    • Optional: only for monitoring third-party Instagram Business Accounts.
  • A Facebook App with the Instagram Public Content Access feature
  • Optional: only for monitoring hashtags

Targets

The targets are comparable to the old instagram targets, but a few have been dropped due to them not being exposed in the Graph API.

See instagram targets for the full list.

New resource types

Instagram access is being made available through two new resource types on Managed Sources for Facebook Pages:

Media and Comments on your Instagram Business Account

If you wish to receive them, you will need to enable comments explicitly using the instagram_comments option; see below.

Parameters

  • type: Must be set to instagram, to indicate that you wish to monitor Instagram content on this page.
  • id: The ID of the Facebook Page, for which you wish to monitor the connected Instagram Business Account.

Example

{
  "parameters": {
    "type": "instagram",
    "id": "130871750291428"
  }
}

Instagram content for a third-party Instagram user

If you wish to receive posts (no comments) for Instagram Business Accounts that you do not manage, this resource type is available.

Parameters

  • type: Must be set to instagram_user to indicate that you wish to monitor a third-party Instagram account.
  • id: The Instagram username of the third-party user you wish to monitor for Instagram content.

Example

{
  "parameters": {
    "type": "instagram_user",
    "id": "nike"
  }
}

Instagram hashtags

Receive anonymised Instagram posts that mention a specific hashtag. The Facebook Graph API allows an Instagram Business Account to query up to 30 unique hashtags. There are also restrictions on how many posts can be received and therefore, with this resource type is not feasible to track/monitor high-volume hashtags such as #cats or #dogsofinstagram.

Parameters

  • type: Must be set to instagram_tag to indicate that you wish to monitor an Instagram hashtag.
  • id: The Facebook Page ID of an Instagram Business Account. Facebook applies a limit of 30 unique hashtags being searched for by an Instagram Business Account.
  • value: The hashtag (without the # prefix) that you’d like to monitor

Example

{
  "parameters": {
    "type": "instagram_tag",
    "id": "130871750291428"
    "value": "obscurehashtag"
  }
}

New Source Parameters Options

The following are new options in addition to the existing options available for Facebook Page Managed Sources.

  • instagram_mentions: Boolean, default: false
    Whether to include third-party Instagram content (both posts and comments) that have photo-tagged your Instagram Business Account.

  • instagram_comments: Boolean, default: false
    Whether to include Instagram comments on posts by your Instagram Business Account.

  • comment_counts: Boolean, default: false
    Whether to generate aggregate comment_count interactions for received posts. Note: this option is shared with Facebook content.

  • like_counts: Boolean, default: false
    Whether to generate aggregate comment_count interactions for received posts. Note: this option is shared with Facebook content.

Full example

A source to monitor the Facebook posts/comments on a Page, and Instagram posts/comments on the Instagram Business Account connected to that Page.

curl -X POST https://api.datasift.com/v1.6/source/create \
  -d 'source_type=facebook_page' \ ← This is all part of the Facebook Graph API
  -d 'name=Combined%20Facebook%20and%20Instagram%20content%20example' \
  -d 'parameters={
    "comments": true,  ← Facebook comments
    "posts_by_others": true, ← Third-party Facebook posts on page
    "instagram_mentions": true, ← Mentions of connected Instagram Business Account
    "instagram_comments": true, ← Comments on posts on Instagram Business Account
    "comment_counts": true ← Facebook and Instagram aggregate comment_counts
  }' \
  -d 'resources=[
    {
      "parameters": {
        "id": "130871750291428" ← Facebook Page to get Facebook content
      }
    },
    {
      "parameters": {
        "type": "instagram",
        "id": "130871750291428" ← Facebook Page to get Instagram content for
      }              connected Instagram Business Account.
    },
    {
      "parameters": {
        "type": "instagram_user",
        "id": "130871750291428", ← Your Facebook Page
        "username": "nike" ← Third-party Instagram username to monitor
      }
    },
    {
      "parameters": {
        "type": "instagram_user",
        "id": "130871750291428", ← Your Facebook Page
        "username": "nikelab" ← Another third-party Instagram username to monitor
      }
    },
    {
      "parameters": {
        "type": "instagram_tag",
        "id": "130871750291428" ← Facebook Page to get Instagram hashtags for
        "value": "obscurehashtag"
      }
    }
  ]' \
  -d 'auth=[{
    "parameters": {
      "value":"EZBXlFZBUg2BYjH3kx42pP5zL6e7JYm8Avkw9ZC0A1NAjidHy1h"
    }, ← Facebook Access Token
    "expires_at":2112112110
  }]' \
  -H 'Authorization: datasift-user:your-datasift-api-key'

FAQs

Are instagram_manage_comments and manage_pages permissions required to receive comments?

You will need:

  • Either the manage_pages permission on your User Access Token or the Page Public Content Access feature enabled on your Facebook App.
  • The instagram_basic permission on your User Access Token.
    However, instagram_manage_comments is required for “Instagram User Mentions”, i.e. getting third-party media in which the monitored user is photo tagged.

What happens with sources that have multiple tokens in the same resources?

All tokens within the same source should have the same permissions on all resources in that source. If a token has insufficient permissions to access the required content on a resource, at some point when the source attempts to use it, an error will be generated (which will appear in the logs) and the token will be temporarily blacklisted for use with any of the resources in that source.
We recommend you split out tokens with different permissions into their own sources.

Does a source need to be stopped and started before updated source options come into effect?

No. Within a minute of the change, we will have updated the source internally and subsequent fetches we do will have the new options

What happens with Image URLs?

The instagram.images.*.url fields will contain canonical URLs for the low, standard and thumbnail resolutions. The only difference is that it will no longer point directly to the image in the CDN, as these URLs are ephemeral. Instead, they will now be a canonical URL that should redirect you automatically to the correct image within their CDN.

How often should I expect to receive comment counts and like counts?

We generate comment/like count interactions when we discover a post for the first time (to capture the initial count) and whenever the count updates. You can distinguish between these two events by the interaction.delta field, which will be 0 for the initial count, and > 0 for all other counts.

What are the restrictions around hashtags?

The new Hashtag search API has some limitations for how many hashtags can be queried in a 7-day rolling window. This is the reason that we require a Facebook Page ID in each instagram_tag resource. You will receive validation errors if you try to use more than your available 30 hashtags.
We also have some restrictions on the amount of media that can be returned from a hashtag search. The API will only return 50 items at a time, with no ability to go back in time. This means we cannot go back 7 days to retrieve recent posts, as we do for other resource types. It also means that high volume hashtags will not receive all media, so please take this into account when deciding which hashtags to monitor.

Can I get comments that contain a hashtag?

The Facebook Graph API does not have the functionality to return comments that contain a hashtag, or comments on media that contain a hashtag in the caption.