README

Grab Instagram content through the Instagram API with Instagram Login.

⚠️ Upgrading from 3.0.0? ⚠️

Meta removed the Basic Display API on 4th December 2024. You will need to create a brand new app per the steps below, rather than repurposing your existing app.

Requirements

This plugin requires Craft CMS 4.0.0 or later.

Installation

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

    cd /path/to/project
   

2. Then tell Composer to load the plugin:

    composer require jsmrtn/craftagram
   

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for craftagram.

Set up

This plugin only presently supports the Instagram API with Instagram Login route for using the API. This means you do not need to have a Facebook page linked to your Instagram professional account.

1. Run thorough the Pre-requisites list below.
2. Log in to https://developers.facebook.com, and in All Apps click Create App.
3. In App details, add your App name and the contact email (which should prefill to your Meta account email).
4. In Use cases, find and click Manage messaging & content on Instagram.
5. In Business Select I don't want to conect a business portfolio yet
6. You will not have any extra requirements, as noted.
7. Create your app.

Instagram Roles

If you do not do this step, you will get errors when continuing to set up your app, with an Insufficient developer roles error.

1. On the redirected dashboard from above, locate the App Roles section in the sidebar and hit Add People.
2. Click Instagram Tester and add your instagram account by slug.
3. Log into your instagram account, and visit the Apps and Websites section
4. Go to Tester invitations and accept the app invite.

Use case

1. Go back to the facebook developer dashboard, locate the Use cases section in the sidebar and hit Customise on the instagram use case.
2. Copy Instagram app ID and Instagram app secret for use in Configuring craftagram below.
3. Click Add account under Generate access tokens, you will be prompted to link your instagram account. You will note it specifies your personal account will be converted to a professional account automatically, if it isn't already. You can select either Business or Creator, depending on your use case.
4. Webbook subscription will automatically be enabled, but this can be disabled, as we do not push any webhooks from this app. For this reason, you can ignore the Configure webhooks section, too.
5. Click Set up under Set up under instagram login. Enter your Primary Site base URL, appended with /actions/craftagram/default/auth (i.e. https://www.yourwebsite.com/actions/craftagram/default/auth) into Redirect URL.

Likewise, you can likely skip app review as generally usage of this plugin is for individual Instagram businesses and not client solutions. Finally, it should be possible to leave your app in Development mode, rather than switching it live.

If you do opt to switch to a live app and send for app review, please note that this is a process separate from this plugin, and I cannot offer support for this process.

Pre-requisites

Instagram Business Account

To create an app with the Instagram API with Instagram Login, you need an Instagram business account. It's a simple process, one that you can do on personal accounts, too, without causing any damage.

1. Go to your profile and tap in the top-right corner.
2. Tap Settings and privacy, then Account type and tools and Switch to professional account.
3. Pick a category that best describes your business, then select Business.
4. All done. You have a business account.

Meta Developer

You must be a registered as a meta developer before you can integrate with their APIs. You can follow this process here.

Configuring craftagram

Go to the settings page for craftagram and enter your App ID and App Secret from the steps above into the required boxes, and hit 'Save'. When the page refreshes, you'll see there's a new button Authorise Craft. Click that button to go to instagram to complete the authorisation procedure.

Tip: The App ID and App Secret settings can be set to environment variables. See Environmental Configuration in the Craft docs to learn more about that.

You with likely be presented a login screen, so enter your login details, then click 'Authorize'. You will be redirected back to Craft with the Long Access Token field populated.

⚠️ Check you're logged in to the correct account before you try to authenticate (or don't be logged in at all). If you're logged in with a different user in the current browser session, you're going to have issues.

Keeping your token active

Instagram tokens expire in 60 days, so you'll need to set up a cron job to keep the token alive. The refresh action is actions/craftagram/default/refresh-token.

For example, this would run the token refresh every month, for all enabled sites with tokens

0 0 1 * * /usr/bin/wget -q https://www.yourwebsite.com/actions/craftagram/default/refresh-token >/dev/null 2>&1

If you just want to update a single site you can add the optional param siteId

0 0 1 * * /usr/bin/wget -q https://www.yourwebsite.com/actions/craftagram/default/refresh-token?siteId=<your siteId> >/dev/null 2>&1

If you fail to set up the cron, you can still refresh the token manaully, by going to the settings page, clicking the Authorise Craft and following the steps outlined above.

⚠️ You cannot refresh access tokens for private Instagram accounts, so ensure the account used in your tester invite above is public

Using craftagram

Using the plugin is pretty simple, for example, for the IMAGE or VIDEO media_type, you could do

{% set craftagram = craft.craftagram.getInstagramFeed() %}

{% if craftagram|length %}
    {% for item in craftagram.data %}
        <img src={{item.media_url}} />
    {% endfor %}
{% endif %}

There are two parameters available to the variable, limit and siteId. The default limit from instagram is 25.

{% set craftagram = craft.craftagram.getInstagramFeed(25, currentSite.id) %}

The plugin returns all fields that are provided from the API endpoint. provided from the API endpoint.

Profile Information

You get first-class support for basic profile information for the connected user.

{% set craftagram = craft.craftagram.getProfileInformation() %}

The plugin returns all fields that are provided from the API endpoint as a JSON object.

Pagination

If you have limits on your feed, you can pass the after (or before if you're paginating backwards) parameter and init an AJAX function to return the data.

Remember to pass limit, and also to pass the correct siteId for the active site, if appropriate.

For example, you could do this to have a 'load more' button:

{% set craftagram = craft.craftagram.getInstagramFeed(10) %}

{% if craftagram|length %}
    <div data-js="insta-wrapper">
        {% for item in craftagram.data %}
            <img src={{item.media_url}} />
        {% endfor %}
    </div>

    <a data-after="{{ craftagram.paging.cursors.after }}" data-js="load-more">Load more</a>
{% endif %}

{% js %}
    $("[data-js=load-more]").click(function(e) {
        e.preventDefault();
        $.get("{{ parseEnv(craft.app.sites.primarySite.baseUrl) }}/actions/craftagram/default/get-next-page?siteId={{ currentSite.id }}&limit=10&url=" + $(this).data('after'), function(res) {
            data = $.parseJSON(res);

            // For each, append the item to our wrapper
            $.each(data["data"], function() {
                $("[data-js='insta-wrapper']").append("<img src="+$(this)[0]["media_url"]+" />");
            });

            // Update the paging with the next after.
            $("[data-js=load-more]").data("after", data["paging"]["cursors"]["after"]);
        });
    });
{% endjs %}

Headless mode

If you're using Craft headless (or generally just need a JSON formatted version of your results), you can access the instagram feed via /actions/craftagram/default/api (or /craftagramApi if you want to save some bytes), which will return the raw JSON data from instagram. You can pass the following parameters:

Security

There is a setting to opt-in to a more secure API endpoint. If you switch it on, you must pass a Basic Auth header to access this endpoint, otherwise you will receive an error. The Username and Password should be for an activated Craft user. Please note that you must enable the secure endpoint for each site individually.

Rate Limits

Be conscious you might be subject to rate limits from instagram, so if you're on a high traffic website you might get rate limited. You can read more about rate limits at instagram's documentation.