marcorieser / statamic-instagram
Statamic Instagram Business API lets you fetch data via the Instagram Business API into your Statamic site.
Requires
- php: ^8.2
- laravel/framework: ^12.40 || ^13.0
- statamic/cms: ^6.11.0
Requires (Dev)
- laravel/pint: ^1.27
- spatie/laravel-ray: ^1.43
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Statamic Instagram Business API lets you fetch data via the Instagram Business API into your Statamic site.
Features
- Fetch Instagram posts via Meta's Instagram Business API
- Fetch Instagram profile data via Meta's Instagram Business API
- Supports Instagram login and Unified login
- Auto refreshing of Instagram login Access Tokens
How to Install
You can install this addon via Composer:
composer require marcorieser/statamic-instagram
How to Use
Installation
- Install the addon
- Create an Access Token and add it to your
.envfile, see Creating a Meta App / an Access Token. If you already have one, add it asINSTAGRAM_ACCESS_TOKEN. - (Optionally) Publish the addon config by running
php artisan vendor:publish --tag=statamic-instagram-config
Creating a Meta App / an Access Token
Since late October 2026, new Meta apps no longer offer API setup with Instagram login.
If your app only offers API setup with Unified login, follow the Unified login steps. Otherwise use the Instagram login steps.
Unified login
You need an Instagram Business or Creator account and a Meta business portfolio (free).
- Create an app at https://developers.facebook.com with the use case
Manage messaging & content on Instagramand connect it to your business portfolio. - Open
Use cases>Customizeand selectAPI setup with Unified login. - Create a configuration with the access token type
System user access token, expirationNever, your Instagram account as asset and the permissioninstagram_basic. - Generate the token and add it to your
.envfile:INSTAGRAM_LOGIN_METHOD=unified INSTAGRAM_ACCESS_TOKEN=your-token - Only if the token has more than one Instagram account assigned: set
INSTAGRAM_USER_ID. You find the IDs athttps://graph.facebook.com/v26.0/me/assigned_instagram_accounts?access_token=your-token.
If the API answers with a permission error, add pages_show_list, pages_read_engagement and business_management to the configuration.
Unified tokens never expire, so the addon does not refresh them.
Meta changes its setup screens regularly. If a label differs, follow Meta's documentation.
Instagram login
You need an Instagram Business or Creator account. Only available for apps that still offer API setup with Instagram login.
- Create an app at https://developers.facebook.com (use case
Other, app typeBusiness) and addInstagramas a product. - Open
API setup with Instagram login. If your Instagram account is not selectable, add it as anInstagram TesterunderApp roles>Rolesand accept the invitation in the Instagram app. - At
1. Generate access tokens, add your Instagram account and generate a token with the permissioninstagram_business_basic. - Add the token to your
.envfile:INSTAGRAM_LOGIN_METHOD=instagram INSTAGRAM_ACCESS_TOKEN=your-token
The token is valid for 60 days. The addon refreshes it automatically, see Refreshing Tokens. For more details see Meta's documentation.
Display the feed
There is a {{ instagram:feed }} tag, that fetches the media from the API and returns them as an array.
- The
limitparameter defaults to12. - The
handleparameter defaults to the first account in the config.
{{ instagram:feed limit="12" handle="rickastley" }}
{{ id }}
{{ caption }}
{{ comments_count }}
{{ is_shared_to_feed }}
{{ like_count }}
{{ media_product_type }}
{{ media_type }}
{{ media_url }}
{{ permalink }}
{{ thumbnail_url }}
{{ timestamp }}
{{ username }}
{{ children }}
{{ id }}
{{ comments_count }}
{{ like_count }}
{{ media_product_type }}
{{ media_type }}
{{ media_url }}
{{ permalink }}
{{ thumbnail_url }}
{{ timestamp }}
{{ username }}
{{ /children }}
{{ /instagram:feed }}
Display a specific media
There is a {{ instagram:media }} tag, that fetches just one specific media.
- The
idparameter is required. - The
handleparameter defaults to the first account in the config.
{{ instagram:media id="18051623968824939" handle="rickastley" }}
{{ id }}
{{ caption }}
{{ comments_count }}
{{ is_shared_to_feed }}
{{ like_count }}
{{ media_product_type }}
{{ media_type }}
{{ media_url }}
{{ permalink }}
{{ thumbnail_url }}
{{ timestamp }}
{{ username }}
{{ children }}
{{ id }}
{{ comments_count }}
{{ like_count }}
{{ media_product_type }}
{{ media_type }}
{{ media_url }}
{{ permalink }}
{{ thumbnail_url }}
{{ timestamp }}
{{ username }}
{{ /children }}
{{ /instagram:media }}
Display profile data
There is a {{ instagram:profile }} tag, that fetches the profile information from the API and returns them as an array.
- The
handleparameter defaults to the first account in the config.
{{ instagram:profile handle="rickastley" }}
{{ id }}
{{ followers_count }}
{{ follows_count }}
{{ media_count }}
{{ biography }}
{{ name }}
{{ profile_picture_url }}
{{ username }}
{{ website }}
{{ /instagram:profile }}
Manipulate an image
You can manipulate external Instagram image URLs with Glide as usual:
{{ instagram:feed }}
{{ glide src="{thumbnail_url ?? media_url}" format="webp" width="500" }}
<img src="{{ url }}" width="{{ width }}" height="{{ height }}" alt="...">
{{ /glide }}
{{ /instagram:feed }}
Since Statamic v5.43.0, Glide supports external URLs with query params. Therefore, v2 of this addon removes the ability to proxy images and drops the ig_proxy modifier.
Refreshing Tokens
This only applies to Instagram login. Unified login tokens never expire and are never refreshed.
A long-lived access token is valid for two months.
This would mean that it has to be refreshed manually before it expires.
When using the {{ instagram:feed }}, {{ instagram:media }} and {{ instagram:profile }} tags,
this is handled automatically for you.
If you use the API exclusively in PHP, please make sure that you update the token yourself via the scheduler:
Schedule::call(fn() => app(InstagramAPI::class)->refreshAccessToken())->weekly();
Please note that the frequency has to be between one day and the mentioned two months until the token expires.
Child Media (Album)
By default, the addon does not fetch child media for e.g. Albums since that requires additional requests to the API.
Therefore children is null.
In case you need child media, you can enable include_child_posts in the addon config.
Using the API in PHP
There is a dedicated InstagramAPI class to interact with the API. Its public methods are:
cacheKey(...$parts): stringprofile(): Profilefeed(): CollectiongetAccount(): AccountgetLimit(): intsetLimit(int $limit): staticgetUserId(): stringgetHandle(): stringsetHandle(string $handle): staticmedia(int $id): ?MediarefreshAccessToken(): bool
For example, this is how you fetch the feed. This will return you a Collection of Media objects.
return app(\MarcoRieser\StatamicInstagram\InstagramAPI::class) ->setLimit(12) ->setHandle('rickastley') ->feed();
License
Statamic Instagram Business API is paid software with an open-source codebase. If you want to use it, you’ll need to buy a license from the Statamic Marketplace. The license is valid for only one project. Statamic itself is commercial software and has its own license.