Feedframer

Instagram API Setup Guide

This guide will help you configure your Instagram app for Feedframer integration.

Prerequisites

  • A Facebook Developer account
  • An Instagram Business or Creator account
  • Access to Meta Developers Portal

Step 1: Create a Meta App

  1. Go to Meta Developers Portal
  2. Click My Apps → Create App
  3. Select Consumer as the app type
  4. Fill in app details:
    • App Name: Feedframer (or your preferred name)
    • App Contact Email: Your email address
  5. Click Create App

Step 2: Add Instagram Basic Display

  1. In your app dashboard, scroll to Add Products
  2. Find Instagram Basic Display and click Set Up
  3. Click Create New App under Instagram App ID
  4. Fill in the required details:
    • Display Name: Feedframer
    • Valid OAuth Redirect URIs:
      • Local: http://localhost:8000/instagram/callback
      • Production: https://your-domain.com/instagram/callback
    • Deauthorize Callback URL: https://your-domain.com/instagram/deauthorize
    • Data Deletion Request URL: https://your-domain.com/instagram/data-deletion
  5. Click Save Changes

Step 3: Configure App Settings

Get Your Credentials

  1. Go to Basic Display → Basic Display Settings
  2. Copy the following values:
    • Instagram App ID → This is your INSTAGRAM_CLIENT_ID
    • Instagram App Secret → This is your INSTAGRAM_CLIENT_SECRET

Add to Environment Variables

Add these to your .env file:

INSTAGRAM_CLIENT_ID=your_app_id_here
INSTAGRAM_CLIENT_SECRET=your_app_secret_here
INSTAGRAM_REDIRECT_URI="${APP_URL}/instagram/callback"

Step 4: Add Test Users (Development)

During development, you need to add Instagram test users:

  1. Go to Basic Display → User Token Generator
  2. Click Add or Remove Instagram Testers
  3. Add your Instagram username
  4. Accept the invitation in your Instagram app:
    • Go to Instagram → Settings → Apps and Websites
    • Under Tester Invites, accept the invitation

Step 5: Required Permissions (Scopes)

Feedframer requires the following Instagram permissions:

  • instagram_basic - Read basic profile info and media
  • instagram_content_publish - (Optional) Future feature support

These scopes are configured in config/instagram.php and requested automatically during OAuth.

Step 6: Switch to Live Mode

Once ready for production:

  1. Complete App Review in Meta Developer Portal
  2. Submit for review with explanation of how you use Instagram data
  3. Once approved, switch from Development to Live mode
  4. Update redirect URIs to production URLs

API Limitations

Development Mode

  • Limited to test users only
  • Maximum 25 test users
  • Token refresh available

Live Mode

  • Available to all Instagram Business/Creator accounts
  • Rate limits apply: 200 requests per hour (per user token)
  • Tokens expire after 60 days (auto-refreshed by Feedframer)

Troubleshooting

Error: "Redirect URI Mismatch"

  • Ensure INSTAGRAM_REDIRECT_URI in .env exactly matches the URI in Meta Developer Portal
  • Check for trailing slashes - they must match exactly
  • For local development, use http://localhost:8000 (no HTTPS)

Error: "Invalid Client ID"

  • Double-check INSTAGRAM_CLIENT_ID in .env matches the Instagram App ID
  • Ensure you're using Instagram App ID, not Facebook App ID

Error: "App Not Live"

  • Add your Instagram account as a tester (see Step 4)
  • Or submit for app review to go live

Tokens Expiring

  • Feedframer automatically refreshes tokens before they expire
  • Tokens are refreshed 7 days before expiration
  • Check logs if refresh fails: storage/logs/laravel.log

Data Structure

Instagram API returns the following data for media:

{
  "id": "instagram_media_id",
  "media_type": "IMAGE|VIDEO|CAROUSEL_ALBUM",
  "media_url": "https://...",
  "thumbnail_url": "https://...",
  "permalink": "https://www.instagram.com/p/...",
  "caption": "Post caption text",
  "timestamp": "2025-01-01T00:00:00+0000",
  "like_count": 100,
  "comments_count": 50
}

Useful Links

Support

For issues specific to:

Last Updated: October 2025