Instagram on Websites: the new landscape since June 1st

Have you noticed a bunch of console errors or missing Instagram feeds all over the internet? Yup. It’s after June 1st, 2016 and Instagram’s new API restrictions have come into effect, meaning much of what we used to be able to do doesn’t work anymore. This is a quick summary of what we can and cannot do anymore.

TL;DR

If you just want a quick cheat sheet for how to embed posts or a user’s feed on a website, skip the next section. But if you want to know why all your tools do not work, the next section should help.

THE NEW LANDSCAPE

client_id vs auth_token
It appears that client_id will no longer work to authenticate. Every API request I have attempted so far requires a token. If you see documentation that instructs you to use either client_id or auth_token to authenticate, expect only the latter to work. Here is a free tool to help you manually generate an Instagram token.

What is Sandbox Mode?
“Sandbox mode” is the (unintuitively-named) gatekeeper walling off most of what you want to do. This is the default status for all clients, that have not undergone the strict submission process. An API client in sandbox mode has extremely limited permissions. In fact, it has fewer permissions than an anonymous user viewing public content because your app basically lives on a tiny desert island in which you are the only Instagram user and only your past twenty posts exist. So, for example, the /media/search endpoint will only return the media you uploaded near a given location, excluding the media from everyone else or any posts beyond your last twenty.

Who are Sandbox Users?
Sandbox users are other Instagram users that you “invite” to your client. The main reason to do this is so that your app will then be able to “see” their last twenty posts in addition to your own. In other words, when they accept the invitation, they show up on the tiny desert island where your app lives. Beware: None of my invitees received a notification when I invited them. I had to tell them to log into Instagram and then visit https://www.instagram.com/developer/clients/sandbox_invites/. They will then have to submit a short, vague form to register as a developer. If they are not developers they will be confused by these questions, but the fortunately the answers do not seem to matter.

Scopes vs Sandbox Mode
It is easy to get confused by the difference between scopes and Sandbox Mode because both limit what your app can and cannot do. Scopes are permissions, as we traditionally think about them. For example, just about anything you want to do besides view your own posts and profile will require the public_content scope. Whether your app is in Sandbox Mode or Live, these rules do not change. Think of scopes like laws or rules that determine what your app has permission to do, whereas the mode determines whether your app lives in the real world (Live) or the tiny desert island (Sandbox Mode).

Submission process (aka GO LIVE)
In order for your app to view public content from anyone besides you or your sandbox users, it will need to “GO LIVE” via the submission/approval process that scrutinizes your exact use case(s) and will reject any use case that does not fit into one of these three boxes:

  • “My app allows people to login with Instagram and share their own content”
  • “My product helps brands and advertisers understand, manage their audience and media rights.”
  • “My product helps broadcasters and publishers discover content, get digital rights to media, and share media with proper attribution.”

If you cannot convince the Instagram lords that your app is serving one of these three purposes, do not expect it to get approved.

HOW TO

This is a quick cheat sheet for things you might want to do with Instagram on the web. In each set of instructions, it is assumed that your Instagram account is already registered as a developer.

How to show your Instagram feed on your website
Yes, you can still do this, although only your most recent twenty posts. Older posts will not be available. To do this you’ll need to:

  1. Register a client
  2. [optional] Use the client ID and client secret from your app to generate an auth token manually
  3. Authenticate using the auth token (not client ID).

Show someone else’s posts on your website
Yes, you can still do this, but the same twenty-post restriction will apply. Also, you can only invite up to ten “Sandbox users” which effectively means you can only show posts from up to 10 different people. Keep in mind that even when they accept the invitation, your token will need to be requested with the public_content scope in order for this to work. To do this you will need to:

  1. Register a client
  2. Under the “Sandbox” tab of edit screen for your client, invite the Instagram user(s) whose posts you want to show to become a “Sandbox user” of your client.
  3. Tell your invitees to check the Sandbox Invites page and accept (they will not be notified). They will have to fill out the cryptic developer questionnaire before they can accept.
  4. [optional] Use the client ID and client secret from your app to generate an auth token manually. NOTE: To show other content from Sandbox users besides yourself you must check the box to request the public_content scope when you request the token.
  5. Authenticate using an auth token (not client ID).

Show posts that have a specific hashtag
This does not really work anymore. You can technically do this by following the same steps as listed above for showing another user’s posts. But remember: in Sandbox Mode you will only get results from the past twenty posts of any of your sandbox users. So unless it is a hashtag that you and your friends use all the time, the results will be sparse. Bummer. I know.

Embed a single photo/video on your site
They want you to use their official embed widget or their oEmbed endpoint which does not require an auth token.

“We provide two ways to programmatically add an Instagram post to your page: an oEmbed endpoint and a simple URL append endpoint. Neither requires an access_token or client_id.”

Good luck getting that widget to match the design of your site.

Follow button
I do not know of a way to do this anymore… at least not in Sandbox mode. For whatever it’s worth, the embedded media widget (see above) contains a “follow” button.

Conclusion

I intend for this article to evolve over time as I learn more about what is and is not possible via the new Instagram API. If I have made any mistakes, or if you have figured out how to do something nifty that is not mentioned here, tell me in the comments and I will add it. We will get through this together.

Epilogue

Please understand that I cannot debug everyone’s apps in the comments of this article. If you want help with a specific project, please contact me directly to schedule a consultation. In almost all cases I can tell you everything you need to know within a single session. I look forward to working with you.