Switching to the new Instagram Basic Display API

Update: The deprecation of the Legacy Instagram API will now take place on the 29th of June 2020.

With Instagram announcing that the current Instagram API will be completely retired on the 2nd of March 2020, now is the time to switch over to the new basic display API.

Any application still using the old API will no longer be able to retrieve data from Instagram following the deprecation of the last media endpoint on the 2nd of March 2020.

Because of this, we’ve been busy switching updating SnapWidget to use the new Basic Display and Instagram Graph API’s. Below are some tips to make the process of updating your own app easier.

Note: The information below is only for app developers. If you’re a user of SnapWidget you do not need to worry about any of this

In order to switch your current application to use the new API, you will require a Facebook Developer account.

Step 1: Create your Facebook app

If you don’t already have a Facebook app for your application, create one now:

1. Go to developers.facebook.com, click My Apps, and create a new app. Once you have created the app and are in the App Dashboard, navigate to Settings > Basic, scroll the bottom of page, and click Add Platform.
2. Choose Website, add your website’s URL, and save your changes.

Step 2: Configure Instagram Basic Display

1. Click Products, locate the Instagram product and click Set Up to add it to your app.
2. Click Basic Display, scroll to the bottom of the page, then click Create New App.
3. In the form that appears, complete each section. More details about each section available here: https://developers.facebook.com/docs/instagram-basic-display-api/getting-started

Step 3: Add your Instagram Test User

1. Navigate to Roles > Roles and scroll down to the Instagram Testers section. Click Add Instagram Testers and enter your Instagram account’s username and send the invitation.
2. Open a new web browser and go to <www.instagram.com> and sign in to your Instagram account that you just invited. Navigate to (Profile Icon) > Edit Profile > Apps and Websites > Tester Invites and accept the invitation.

You will now be able to begin making changes to your existing application to access to the new Basic Display API. For this, you will need the App ID, App Secret and Redirect URL of the Instagram App you just created.

Note: This is for the Instagram app, not the Facebook application.

The API endpoints you will be using are:

• Authentication: https://api.instagram.com/oauth/authorize
• Getting an access token: https://api.instagram.com/oauth/access_token
• Getting a long-lived token: https://graph.instagram.com/access_token
• Querying user profile and media: https://graph.instagram.com

The steps below briefly explain how to authenticate your user, get a token, exchange it for a long-lived one and query the media for the authenticated user. You will need to update your application accordingly.

Using PHP?

Here is a composer package we created that handles these steps for you: https://packagist.org/packages/espresso-dev/instagram-basic-display-php

Step 4: Authenticate your user

Construct the following authentication URL for your users using the values from your Instagram app:

https://api.instagram.com/oauth/authorize
    ?client_id={app-id}
    &redirect_uri={redirect-uri}
    &scope=user_profile,user_media
    &response_type=code

Open this URL in a new window, and allow your users to sign in with their Instagram accounts.

Keep in mind until your app is approved by Facebook / Instagram you will only be able to sign in with the test user you configured in step 3.

Once the user has accepted permissions, the page will redirect to your redirect URL where you will be able to get the authorization code that is included. For example:

https://yourapplication.com/auth/?code=AQDp3TtBQ...

Step 5: Exchange the Code for a Token (short-lived)

You will need to perform POST request to the following endpoint to exchange the code for a token:

https://api.instagram.com/oauth/access_token

Include the following POST parameters:

client_id={app-id}
client_secret={app-secret}
grant_type=authorization_code
redirect_uri={redirect-uri}
code={code}

On success, the API will return a JSON object with the short-lived Instagram User Access Token:

{ 
    "access_token": "IGQVJ...", 
    "user_id": 17841405793187218 
}

Since a token that is only valid for 1 hour would not be very useful, you can now exchange it for a long-lived token that is valid for 60 days.

Step 6: Exchange the short-lived token for a long-lived token

Your request must be made server-side and include:

• A valid (unexpired) short-lived Instagram User Access Token
• Your Instagram App Secret (App Dashboard > Products > Instagram > Basic Display > Instagram App Secret)

To exchange the token, perform a GET request to the following endpoint and include the required query params:

https://graph.instagram.com/access_token
    ?grant_type=ig_exchange_token
    &client_secret={instagram-app-secret}
    &access_token={short-lived-access-token}

On success, the API will return a JSON object with the long-lived Instagram User Access Token:

{
    "access_token":"{long-lived-user-access-token}", 
    "token_type": "bearer", 
    "expires_in": 5183944 // Number of seconds until token expires 
}

You can now use this access token to query the user profile and media.

Step 7: Query the user profile and media

To retrieve the authenticated users profile and media, you will need to perform GET requests to the following endpoints:

https://graph.instagram.com/me?fields=id,username&access_token={access-token}

https://graph.instagram.com/me/media?fields=id,caption&access_token={access-token}

More information about the available fields here.

Step 8: Submit your application for approval

Once you’ve made the required changes to your application, you are ready to submit your application for approval.

If you have an application that is already live, you will need to create a test application on Facebook, and use that during the approval process. Once permission has been approved, you will be able to use the permissions on your live app.

To create a new test app, select your app from the dashboard: https://developers.facebook.com/apps and then drop down on the left, choose Create Test App

You can now use this test app as part of the submission process.

To start the submission, select Instagram > Basic Display from the products in the left sidebar. Then add the required permissions for your app.

Once added, you will need to edit the details and complete the submission for each.

You will need to do this for each of the permissions.

Here is a template for the detailed description section that you can use with your submission:

My app uses the {instagram_graph_user_profile / instagram_graph_user_media} permission to be able to {main feature permission is required for}. My app allows {benefits of your app}.

Examples of a screencast: https://developers.facebook.com/docs/apps/review/screencast/

Or reach out and we’ll share our screencast with you.

After completing the details for each permission. You will need to edit the details for App Verification.

The Testing Credentials section can be used to provide details for the Facebook team to check your application. Here is a template to use to make the process a little easier:

Site URL: {url to your stage/test environment} Testing email: {login that the Facebook team can use} Testing password: {password for the login}

To see how "instagram_graph_user_profile" and "instagram_graph_user_media" is used in my app:

1. Navigate to {your site url}
2. Login using the credentials provided
3. ...

Try to be as detailed as possible, and make sure you have tested the process yourself using the provided login credentials.

On average it looks like approval takes about 5 business days.

Good luck!

Using PHP?

If you’re using PHP, here is a composer package we created that makes using the Instagram Basic Display API a little easier: https://packagist.org/packages/espresso-dev/instagram-basic-display-php