Someone over there on Instagram must really hate developers. That, or they don’t like much the idea of you showing their content on your site and they try to make it harder and harder with every API update. To be fair, it’s been two years since Instagram (aka Facebook) announced that they are going to shut down their old APIs. So, the time has come and after a small delay (mostly because of COVID-19), on June 29 the Instagram Legacy API will no longer be available. What this probably means is that if you used the API to fetch Instagram photos on your website, that part of your app will stop working.
“OK then”, you might rightfully say, “let’s just use the new API”. Well, apparently it’s not so easy, as it needs some special handling compared to the old one. Plus, a complete, concise tutorial is nowhere to be found yet (or at least I couldn’t find one). The clock is ticking, though, so I had to dig into the documentation to figure this out, and here is what I learned.
Part 1: Generate the Token
- The first thing you need is a so-called long-lived token that will permit you to access the user’s media. To generate that Token, you have to create a new Facebook App on developers.facebook.com.There, you follow the straightforward on-screen instructions to create a new App ID.
- Next, you need to set up Instagram. On your Apps list, go to the newly created app and click on “Add a Product“.
- On the products list that will open, scroll until you find Instagram, and click “Set Up“.
- Then, on the next screen, click on “Basic Display” and “Create New App“.
- Add valid URLs (basically, this can simply be the link of your site) and Save your changes.
- Then, you need to create a new token. To do so, you first need to add as an Instagram Tester the user whose photos you need to fetch, by clicking first on “Add or Remove Instagram Testers” and then “Add Instagram Testers“: This will send an invitation to the Instagram user, which they must accept in the Apps and Websites section of their profile. As soon as they do that, you are ready to go and create your token.
- To generate your token, you have to go back to the Basic Display, scroll down to the “User Token Generator” and click on the “Generate Token” button. Keep in mind that tokens can only be generated for public Instagram accounts.
For the token to be generated, the Instagram user needs to give their permission. After doing so, the token will be ready to copy and use it on your App.
Part 2: Coding your app
TL;DR: If you don’t mind about the details, just go get the code that fetches the Instagram entries and stores them into an array. If you do, the explanation follows.
Getting the Token was the easy part. If you are creating an app solely to generate access tokens with the User Token Generator, you do not need to submit your app for App Review. The User Token Generator does not require any permissions and can be used while your app is in Development Mode. So, if all you want is to fetch the recent photos of a public Instagram account on your site, you are ready to go to the implementation part.
Fetching data from the Instagram Basic Display API
Here’s where it gets tricky, though: Contrary to the old implementation, the new API requires you to make multiple calls to fetch your photos. More specifically, first, you have to make a call to the User endpoint of the Instagram Basic Display API. This call requires two parameters: The token that we generated earlier, and the User ID, which should not be confused with the App ID that you might notice on the screens of the earlier steps. To find the correct ID, you can paste the token to the Access Token Debugger, which will show you, among other info, the User ID that you need.
The User endpoint will only return the latest media IDs of the given account. That means that you don’t have access to the photos’ URLs or the links to the actual Instagram posts. To get them, you need to loop over the media IDs, and for each one of them, make another call to the Media endpoint.
“Ok, it’s not such a big deal”, you might say. Well, actually there are two more things that we need to take care of before deploying our code.
Dealing with the Instagram rate limiting
The first one is that Instagram has some limits to the number of calls your app can make per hour. On a relatively high-traffic site, this might be a problem. That’s why I figured that a nice way to deal with it is to store the call in a WordPress transient, which will expire every hour. That way, you will only have to call the API once every hour and store its results to the database.
Refreshing the Token
Long-lived access tokens like the one that you created on the earlier steps are only valid for 60 days, after which they expire and you will have to generate them again. Luckily, Instagram offers a way to refresh them by making another API call. Refreshing a long-lived token makes it valid for 60 days again and you can do it only for tokens that are at least 24 hours old. Long-lived tokens that have not been refreshed in 60 days will expire. So, why not make that call once every hour too, along with the rest of the code? It will ensure that the API is always fresh and if it’s newer than 24 hours, it will simply get ignored. I didn’t see any warning against that, so I guess that it conforms to Instagram’s rules.
Eventually, we end up with the following function, which will return an array of photos for us to present them whichever way we like. Besides the obvious $token and $user parameters, which are the only ones that are mandatory, you can also modify the number of entries to be fetched, the fields to be returned, as well as the acceptable media types. I’ve also included some inline comments to further explain the code.
That’s all! It wasn’t easy, but now that we ‘ve put it all in order, it doesn’t seem so intimidating anymore, either. Of course, if you know of a better way to fetch Instagram photos on WordPress, let me know in the comments!