PHPackages jsmrtn/craftagram - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. jsmrtn/craftagram ActiveCraft-plugin[API Development](/categories/api) jsmrtn/craftagram ================= Grab Instagram content through the Instagram API 4.3.0(6mo ago)141.6k↓69.9%9[1 issues](https://github.com/jsmrtn/craftagram/issues)proprietaryPHP Since Mar 11Pushed 3mo ago3 watchersCompare [ Source](https://github.com/jsmrtn/craftagram)[ Packagist](https://packagist.org/packages/jsmrtn/craftagram)[ RSS](/packages/jsmrtn-craftagram/feed)WikiDiscussions v4 Synced yesterday READMEChangelog (10)Dependencies (1)Versions (44)Used By (0) craftagram plugin for Craft CMS 4.x / 5.x ========================================= [](#craftagram-plugin-for-craft-cms-4x--5x) 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 ------------ [](#requirements) This plugin requires Craft CMS 4.0.0 or later. Installation ------------ [](#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 ------ [](#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 , 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 [](#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](https://www.instagram.com/accounts/manage_access/) section 4. Go to *Tester invitations* and accept the app invite. ### Use case [](#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. ) 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 [](#pre-requisites) #### Instagram Business Account [](#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 [](#meta-developer) You must be a registered as a meta developer before you can integrate with their APIs. You can follow this process [here](https://developers.facebook.com/docs/development/register). Configuring craftagram ---------------------- [](#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 [](#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= >/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-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 %} {% 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) %} ``` Field NameDescriptionlimitThe default limit from instagram is 25siteIdThe current site's ID. If you only have one site on your install you can leave this blank, otherwise pass the `siteId` for the site you have added the authorisation to. You can hard-code the site ID if you have only set up authorisation on one of your multi-site installs, otherwise pass the current `siteId` dynamicallyThe plugin returns all fields that are [provided from the API endpoint.](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-media#fields) provided from the API endpoint. ### Profile Information [](#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](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/get-started#fields) as a JSON object. ### Pagination [](#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 %} {% for item in craftagram.data %} {% endfor %} Load more {% 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(""); }); // Update the paging with the next after. $("[data-js=load-more]").data("after", data["paging"]["cursors"]["after"]); }); }); {% endjs %} ``` ### Headless mode [](#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: URL ParameterDescriptionlimitThe default limit from instagram is 25siteIdThe current site's ID. If you only have one site on your install you can leave this blank, otherwise pass the `siteId` for the site you have added the authorisation to. You can hard-code the site ID if you have only set up authorisation on one of your multi-site installs, otherwise pass the current `siteId` dynamicallyurlPass the `after` or `before` parameters from `data->paging->cursors` to get the next or the previous set of results#### Security [](#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 [](#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](https://developers.facebook.com/docs/graph-api/overview/rate-limiting#instagram). ### Health Score 51 — FairBetter than 95% of packages Maintenance73 Regular maintenance activity Popularity30 Limited adoption so far Community17 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 92.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~53 days Total 42 Last Release 113d ago Major Versions 1.4.5 → 2.0.02022-06-30 1.4.6 → v2.x-dev2024-01-16 v2.x-dev → 3.0.0-beta2024-05-22 v3.x-dev → 4.0.0-beta2024-10-22 ### Community Maintainers ![](https://www.gravatar.com/avatar/1fd659476d9a346d1f5ee3696913c1552825d5e6052153f15d3153898612c980?d=identicon)[jsmrtn](/maintainers/jsmrtn) --- Top Contributors [![jsmrtn](https://avatars.githubusercontent.com/u/1694957?v=4)](https://github.com/jsmrtn "jsmrtn (128 commits)")[![boboldehampsink](https://avatars.githubusercontent.com/u/378974?v=4)](https://github.com/boboldehampsink "boboldehampsink (4 commits)")[![Saboteur777](https://avatars.githubusercontent.com/u/9061795?v=4)](https://github.com/Saboteur777 "Saboteur777 (3 commits)")[![simonleadbetter](https://avatars.githubusercontent.com/u/1379783?v=4)](https://github.com/simonleadbetter "simonleadbetter (3 commits)")[![darrylhein](https://avatars.githubusercontent.com/u/376976?v=4)](https://github.com/darrylhein "darrylhein (1 commits)") --- Tags cmsCraftcraftcmscraft-plugincraftagram ### Embed Badge ![Health badge](/badges/jsmrtn-craftagram/health.svg) ``` [![Health](https://phpackages.com/badges/jsmrtn-craftagram/health.svg)](https://phpackages.com/packages/jsmrtn-craftagram) ``` ### Alternatives [verbb/formie The most user-friendly forms plugin for Craft. 102393.6k69](/packages/verbb-formie)[wrav/oembed A simple plugin to extract media information from websites, like youtube videos, twitter statuses or blog articles. 36208.3k3](/packages/wrav-oembed)[verbb/vizy A flexible visual editor field for Craft. 4250.4k](/packages/verbb-vizy)[verbb/hyper A user-friendly links field for Craft. 24147.8k12](/packages/verbb-hyper)[scaramangagency/craftagram Grab Instagram content through the Instagram API 1426.1k](/packages/scaramangagency-craftagram)[verbb/events A full-featured plugin for event management and ticketing. 2311.9k](/packages/verbb-events) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)