Instagram Managed Sources - IMPORTANT


#1

Update: 2018-11-15 - Third-Party Instagram Account Support

As mentioned at the bottom of this post. The engineering team have updated the way we fetch posts for Instagram Business Accounts that you do not own/manage. The API remians the same for this (see instagram_user resource type), but the implementation is more efficient. The reason for the improvements is that the Graph API does not allow fetching comments for accounts you do not manage. Therefore we can make our job scheduling simpler and therefore more efficient.


Update: 2018-11-13 - Hashtag Search Support

The engineering team has worked hard to introduce support for the new Instagram Hashtag Search API. This post has been updated with API request examples, the required permissions/features your Facebook App needs and what restrictions there are on the data that can be queried and returned.


On 11th December 2018, the existing Instagram Managed Source will stop functioning due to the permanent removal of the current Instagram Platform API: https://www.instagram.com/developer/. In its place, Instagram has announced their new API which sits on top of the Facebook Graph API: https://developers.facebook.com/products/instagram/

This will affect all Instagram Managed Source users. We have implemented some changes to the User interface and our API to support this new API provided by Instagram/Facebook. There are also several features that Instagram will no longer be able to support or will have more limited functionality.

Facebook Application Approval

It is highly recommended that you use the Facebook Managed source via the API and with your own generated access tokens. To do this, you need to have a Facebook Application with the new Instagram permissions approved. It is recommended that you go through this approval as soon as possible as the process may be iterative. https://developers.facebook.com/docs/instagram-api/getting-started/

Managed Sources for Instagram on Facebook’s Graph API

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

The new API only allows access to Instagram Business Accounts. 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

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

This is currently not available if authenticating with the DataSift Facebook Application through the UI. To enable this functionality, you will need to have your own application approved for the instagram_manage_insights permission.

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

To enable this functionality, you will need to have your own application approved for the Instagram Public Content Access feature.

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_count: Boolean, default: false
    Whether to generate aggregate comment_count interactions for received posts. Note: this option is shared with Facebook content.
  • like_count: Boolean, default: false
    Whether to generate aggregate comment_count interactions for received posts. Note: this option is shared with Facebook content.

Example

{
  "parameters": {
    "instagram_mentions": true,
    "instagram_comments": true,
    "comment_count": true,
    "like_count": true
  }
}

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_count": 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'

Schema Differences

All Instagram interactions will keep the Instagram interaction type and the schema will match as closely as possible given the new API restrictions. The following is a list of the differences between the legacy Managed Sources for Instagram, and the new Managed Sources for Instagram on the Facebook Graph API.

Unavailable Fields

  • instagram.caption.id
  • instagram.carousel_media.images.low_resolution.height
  • instagram.carousel_media.images.low_resolution.width
  • instagram.carousel_media.images.standard_resolution.height
  • instagram.carousel_media.images.standard_resolution.width
  • instagram.carousel_media.images.thumbnail.height
  • instagram.carousel_media.images.thumbnail.width
  • instagram.carousel_media.images.users_in_photo.position.x
  • instagram.carousel_media.images.users_in_photo.position.y
  • instagram.carousel_media.images.users_in_photo.user.username
  • instagram.carousel_media.images.videos.low_bandwidth.height
  • instagram.carousel_media.images.videos.low_bandwidth.width
  • instagram.carousel_media.images.videos.low_bandwidth.id
  • instagram.carousel_media.images.videos.low_bandwidth.url
  • instagram.carousel_media.images.videos.low_resolution.height
  • instagram.carousel_media.images.videos.low_resolution.width
  • instagram.carousel_media.images.videos.low_resolution.id
  • instagram.carousel_media.images.videos.low_resolution.url
  • instagram.carousel_media.images.videos.standard_resolution.height
  • instagram.carousel_media.images.videos.standard_resolution.width
  • instagram.carousel_media.images.videos.standard_resolution.id
  • instagram.filter
  • instagram.geo.latitude
  • instagram.geo.longitude
  • instagram.images.low_resolution.height
  • instagram.images.low_resolution.width
  • instagram.images.standard_resolution.height
  • instagram.images.standard_resolution.width
  • instagram.images.thumbnail.height
  • instagram.images.thumbnail.width
  • instagram.location.id
  • instagram.location.name
  • instagram.media.filter
  • instagram.users_in_photo.position.x
  • instagram.users_in_photo.position.y
  • instagram.users_in_photo.position.user.username
  • instagram.videos.low_bandwidth.height
  • instagram.videos.low_bandwidth.width
  • instagram.videos.low_bandwidth.id
  • instagram.videos.low_bandwidth.url
  • instagram.videos.low_resolution.height
  • instagram.videos.low_resolution.width
  • instagram.videos.low_resolution.id
  • instagram.videos.low_resolution.url
  • instagram.videos.standard_resolution.height
  • instagram.videos.standard_resolution.width
  • instagram.videos.standard_resolution.id
  • interaction.geo.latitude
  • interaction.geo.longitude

Additional fields unavailable for media matching a hashtag search

Facebook remove all time/date and author information from media matching hashtag queries

  • instagram.caption.created_at
  • instagram.caption.created_time
  • instagram.caption.from.username
  • instagram.created_at
  • instagram.created_time
  • instagram.from.username
  • instagram.id
  • instagram.media.created_at
  • instagram.media.created_time
  • instagram.user.username
  • interaction.author.username

FAQ

  • 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.