Instagram Import Guide

Automatically sync your Instagram portfolio to your barbershop website. This guide walks you through setting up and using the Instagram import feature.

Overview

The Instagram import feature allows you to automatically pull your latest Instagram posts and display them in your gallery. The CLI uses the Instagram Basic Display API to fetch your media, uploads it to Cloudinary for optimized delivery, and stores it in your database.

Compliance: This feature complies with Instagram's API terms of service and only accesses public media that you've authorized.

Prerequisites

Before you can use Instagram import, you need:

An Instagram Business or Creator account
Instagram Basic Display API credentials
Cloudinary account and credentials
A valid tenant ID in your database

Setup Instructions

Create Instagram App

Go to Facebook Developers and create a new app. Select "Consumer" as the app type and add "Instagram Basic Display" product.

Configure your app settings:

Add your website URL as a valid OAuth redirect URI
Note your App ID and App Secret

Get Access Token

Generate a long-lived access token for your Instagram account. You can use the Instagram Basic Display API's token generator or implement the OAuth flow.

# Example: Using Instagram's token generator
# Visit: https://developers.facebook.com/tools/explorer/
# Select your app and generate a User Token
# Exchange short-lived token for long-lived token

Token Expiration: Long-lived tokens expire after 60 days. You'll need to refresh them periodically or implement automatic token refresh.

Configure Cloudinary

Cloudinary will be used to:

Store and optimize your Instagram media
Provide fast CDN delivery
Generate responsive image variants

Set Environment Variables

Add the following to your .env file:

# Instagram Configuration
INSTAGRAM_ACCESS_TOKEN=your-long-lived-access-token

# Cloudinary Configuration
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Database (required)
MONGO_URI=mongodb://localhost:27017/branded-barber

Using the Import Command

Once configured, you can import your Instagram posts:

# Import latest 20 posts (default)
branded-barber import instagram -t tenant-1

# Import specific number of posts
branded-barber import instagram -t tenant-1 --limit 50

# Dry run to see what would be imported
branded-barber import instagram -t tenant-1 --dry-run

The command will:

Fetch your latest Instagram media
Upload images/videos to Cloudinary
Store metadata in your database
Skip duplicates (based on external ID)

Command Options

branded-barber import instagram [options]

Options:
  -t, --tenant-id <id>    Tenant ID (required)
  --limit <number>        Number of posts to import (default: 20)
  --dry-run              Preview what would be imported without making changes
  -h, --help             Display help

Automation

To keep your gallery up-to-date automatically, you can set up a cron job or scheduled task:

# Example: Run daily at 2 AM (cron)
0 2 * * * /usr/local/bin/branded-barber import instagram -t tenant-1 --limit 10

# Or using GitHub Actions, Railway Cron, etc.

Best Practice: Import smaller batches (10-20 posts) regularly rather than large imports infrequently. This reduces API rate limit issues and keeps your gallery fresh.

Troubleshooting

Token Expired: If you get authentication errors, your access token may have expired. Generate a new long-lived token and update your environment variables.

Rate Limits: Instagram API has rate limits. If you hit limits, wait before retrying. The CLI will show rate limit errors if encountered.

Cloudinary Errors: Ensure your Cloudinary credentials are correct and your account has sufficient storage/quota.

No Media Found: Verify your Instagram account has public posts and that the access token has the correct permissions.

Privacy & Compliance

This feature is designed to comply with Instagram's terms of service:

Only accesses media you've authorized
Does not store Instagram credentials
Respects user privacy settings
Uses official Instagram APIs

See our Privacy Policy for more information about how we handle your data.