Table of Contents

• Features
• Installation
• Configuration
  • Local developement
  • How to setup Instagram Basic Display API to download images
• API
• Troubleshooting
  • Most common errors
  • Emojis in content causing errors
  • Issues
• Migration
• Credits

Features

• Download last 20 images from Instagram whenever the API endpoint is called with a 10 minute interval
• Can download images from albums/carousels. (Will be saved as separate images with same mediaId)
• Uses Instagram Basic Display API
• Uses Strapi draft and publish system to provide a way to temporarily hide images (published by default)
• Due to refetching images it prevents the image url's from becoming invalid
• Save permalinks to posts in the database
• Allows videos to be downloaded as well in order to obtain a thumbnail

Installation

The plugin can be installed through npm:

npm install -S @sven902/strapi-plugin-instagram-images

Secondly don't forget to enable the plugin in your Strapi project (config/plugins.ts):

'instagram-images': {
    enabled: true
}

Configuration

Local developement

Important: The redirect URL's that are used in the Instagram connection don't accept localhost nor http URLs. Therefore, you need to have a domain and a SSL certificate to use this plugin. A way to use and test this plugin locally is to use a service like ngrok with the following command: ngrok http 1337. Make sure that you connect to the Strapi CMS through the ngrok URL as the Instagram redirect URLs generated by the plugin will be based on the URL you are using (window.location).

How to setup Instagram Basic Display API to download images

1. Go to the Facebook for Developers website and create a new app.
2. Go to the app dashboard and add the Instagram Basic API.
3. Add a new test user in the Instagram Test Users tab. See Meta developer docs for more information.
4. Go to https://www.instagram.com/accounts/manage_access/ in order to accept the permissions for the app as a test user.
5. Open up the settings tab in the Strapi admin panel and fill in the Instagram app ID & Secret.
6. If correctly setup you should be able to click on the authenticate button and login with the Instagram account that you have added as a test user.
7. After logging in you should be redirected back to the Strapi admin panel and see a success message.
8. You should be able to use the 'Download images' button to download the last 20 images from the Instagram account that you have added as a test user.
9. The images should now be available in the Instagram images collection type.
10. You can now use the API endpoint to fetch the images. See the API section for more information.
11. Extra: make sure you enabled the right permissions in order to call the API endpoint to fetch the images.

API

After setup you can call the following API endpoint to fetch the images:

/api/instagram-images/images

This should work as a normal Strapi content type endpoint.

However, there's is one difference: the GET request is overwritten to refresh the access token and fetch the images from Instagram. Because of this, there is no need to reauthenticate as long as the access token is valid (which should be automatically refreshed). This refreshment of images and tokens is throttled to a 10 minute interval. If in any case the access token is invalid or you want to manually fetch the images, you can use the 'download images' or the authenticate button in the settings page to manually trigger those actions.

Troubleshooting

If you have any error in the authentication process or the plugin don't have short or long lived token you should check Last Instagram Api response and developer tool's console for error messages.

Most common errors

• Double check if your callback url is correct in the Instagram app settings. It should be the same as the one in the Strapi settings.
• Make sure you have added a test user in the Instagram Test Users tab and accepted the request in the Instagram permissions page on the account. If not, you will get an error message like Invalid OAuth access token or a general Permission Error.
• Save button might be stuck if nothing is changed on the settings page. Simply edit some parameters in order to save the settings.
• Make sure you have the right permissions to call the API endpoint. You can check this in the roles & permissions section in the Strapi admin panel.

Emojis in content causing errors

In order for the database to save emoji's properly you should make sure the encoding of both the table & connection is set to utf8mb4. For the connection this can be done by adding the following line to your database configuration (in /config/database.js) in the connection configuration:

charset: env('DATABASE_CHARSET', 'utf8mb4'),

Issues

If you think you found a problem or bug feel free to open an Issue at Github.

Migration

If you are using the original plugin and want to migrate to this plugin you can follow these steps:

1. Note that the data is saved separately in the database as this is a 'different' plugin. Therefore, you need to redo the steps in the configuration section in order to download the images again.
2. Change your API url's for fetching (or any other action) from /api/instagram/images to /api/instagram-images/images.
3. You can delete the old plugin from your project by running npm uninstall strapi-plugin-instagram.
4. You can also remove the old images as you will probably have a duplicate of collection entities for the images.

Credits

The original plugin was created by Kepes. After finding some critical bugs I proposed a PR to fix them. Unfortunately, The PR has yet to be merged and the plugin hasn't had an update for almost a year by now. Therefore, I decided to copy my fork with the fixes, adjusted it for typescript and publish it as a new package in order to provide further maintenance and maybe the addition of new features. The original plugin can be found here.