n8n-nodes-instagram-integrations

n8n-nodes-instagram-integrations

Professional N8N community nodes for seamless Instagram Messaging API integration with OAuth2 authentication.

Installation • Features • Prerequisites • Quick Start • Documentation • Support

📖 Overview

This package provides comprehensive Instagram integration for n8n workflows, enabling automated messaging, media management, and webhook-based event handling through the official Instagram Graph API.

Perfect for:

• 🤖 Automated customer support via Instagram DM
• 📢 Marketing campaigns and notifications
• 🎯 Lead generation and engagement
• 📊 Customer interaction tracking
• 🔄 Multi-platform messaging automation

✨ Features

🔐 OAuth2 Authentication

• One-click authentication - Secure OAuth2 flow similar to Google Drive
• 🆕 Automatic long-lived tokens - Short-lived tokens (1 hour) automatically exchanged for long-lived tokens (60 days)
• 🆕 Automatic token refresh - Tokens refresh automatically before expiration (zero configuration)
• 🆕 No more "refreshToken is required" errors - Smart token lifecycle management prevents expiration issues
• Multiple credential types - OAuth2 or manual access token
• Auto-discovery - Automatically fetches Instagram Business Account ID

📬 Instagram Messaging Node

Message Types:

• 💬 Text Messages - Send formatted text with up to 1000 characters
• 🖼️ Image Messages - Share images via public HTTPS URLs
• 🎵 Audio Messages - Send voice messages and audio files
• 🎬 Video Messages - Share video content
• 📤 Media Upload - Upload and publish photos, videos, reels, and stories

Interactive Templates:

• 🔘 Button Templates - Up to 3 action buttons (web links or postbacks)
• 🎴 Generic Templates - Carousel cards with images and buttons
• ⚡ Quick Replies - Up to 13 quick response options

User Management:

• 👤 Get User Profile - Retrieve user information (name, username, profile picture)

� Instagram Content Publishing (NEW!)

Post Creation:

• 📷 Single Posts - Create image or video feed posts
• 🎞️ Carousel Posts - Multi-media posts (2-10 images/videos)
• 🎬 Reels - Short-form videos up to 60 seconds
• 📋 Stories - 24-hour temporary content

Advanced Features:

• 🏷️ User Tagging - Tag up to 20 users with precise positioning
• 🛍️ Product Tagging - Tag products from Facebook catalog
• 🤝 Collaborators - Tag other accounts as collaborators
• 📍 Location Tagging - Add location stickers to posts
• 🎨 Custom Thumbnails - Set video thumbnail positions
• 🎵 Audio Attribution - Name audio tracks in reels

Media Management:

• 📊 List Media - Get paginated list of your media
• 🔍 Get Media Details - Retrieve specific media information
• 👶 Get Carousel Children - Access individual carousel items

Instagram Trigger Node

Webhook Events:

• 💬 New Messages - Trigger on incoming messages
• 🔘 Postback Events - Handle button clicks and interactions
• ✅ Opt-in Events - Process user consent actions
• 💭 Comments (NEW!) - Trigger when someone comments on your media
• 🏷️ Mentions (NEW!) - Trigger when someone mentions you in comments or stories

Dual Output System:

• Output 1 (Messages/Postbacks/Opt-ins) - Direct messaging events
• Output 2 (Comments/Mentions) - Content engagement events

Security Features:

• 🔒 Webhook signature validation (X-Hub-Signature-256)
• ✓ Verify token authentication
• 🛡️ HMAC SHA256 cryptographic verification

📋 Prerequisites

Required Accounts

• Facebook Page - Active Facebook page
• Instagram Business Account - Connected to your Facebook page
• Meta Developer Account - Access to Facebook Developer Console
• n8n Instance - Self-hosted or cloud (version 0.196.0+)

Required Permissions

For Messaging:

• instagram_basic - Basic profile access
• instagram_manage_messages - Send and receive messages
• pages_manage_metadata - Webhook subscriptions
• pages_read_engagement - Read engagement data

For Content Publishing (NEW):

• instagram_content_publish - Create and publish posts, reels, and stories
• pages_show_list - List Facebook pages
• catalog_management - Product tagging (optional, for Instagram Shopping)

Technical Requirements

• Node.js 18.15+ or 20.10+
• n8n version 0.196.0 or higher
• HTTPS webhook endpoint (for trigger node)

🚀 Installation

Option 1: n8n Community Nodes (Recommended)

• Open n8n
• Go to Settings → Community Nodes
• Search for n8n-nodes-instagram-integrations
• Click Install
• Restart n8n

Option 2: npm Installation

cd ~/.n8n/nodes
npm install n8n-nodes-instagram-integrations

Option 3: Docker

Add to your docker-compose.yml:

services:
  n8n:
    environment:
      - N8N_COMMUNITY_PACKAGES=n8n-nodes-instagram-integrations

🎯 Quick Start

Step 1: Create Meta App

• Visit Meta for Developers
• Click Create App
• Select Business type
• Add Instagram product
• Note your App ID and App Secret

Step 2: Connect Facebook Page

• In App Dashboard → Instagram → Basic Display
• Add your Instagram Business Account
• Generate a Page Access Token with required permissions
• Copy the Instagram Business Account ID

Step 3: Configure n8n Credentials

Using OAuth2 (Recommended):

• In n8n: Credentials → New → Instagram OAuth2 API
• Enter:
  • Client ID: Your App ID
  • Client Secret: Your App Secret
• Click Connect my account
• Authorize in popup window
• ✅ Connection established!

Using Access Token:

• In n8n: Credentials → New → Instagram Access Token API
• Enter:
  • Access Token: Your Page Access Token
• Click Save
• ✅ Account ID auto-discovered!

Step 4: Build Your First Workflow

• Create new workflow
• Add Instagram node
• Select Message → Send Text Message
• Configure:
  • Credential: Your Instagram credential
  • Recipient ID: Target user's Instagram-scoped ID
  • Message: Your text content
• Execute!

📚 Documentation

Core Guides

• 📘 CHANGELOG.md - Version history and updates
• 🔧 IMPLEMENTATION_GUIDE.md - Developer documentation
• � AUTHENTICATION_GUIDE.md - Setup and OAuth guide
• �📋 Instruction Files - Technical specifications

Content Publishing Guides (NEW!)

• 🚀 QUICKSTART.md - Get started in 5 minutes
• 📸 POST_STORY_GUIDE.md - Complete post/story creation guide
• 💡 EXAMPLES.md - Code examples and workflow patterns
• 📊 FEATURE_SUMMARY.md - Technical implementation details

Example Workflows

Messaging:

• Auto-Reply to Messages
• Daily Announcements
• Customer Support Bot

Content Publishing:

• Scheduled Daily Posts
• Automated Carousels
• Story Automation
• Product Showcase Reels

API Reference

Message Operations:

• sendTextMessage - Send text content
• sendImageMessage - Send image via URL
• sendAudioMessage - Send audio file
• sendVideoMessage - Send video content
• sendButtonTemplate - Interactive buttons
• sendGenericTemplate - Carousel cards
• sendQuickReplies - Quick response options
• uploadMedia - Upload media files

Post Operations (NEW):

• createSinglePost - Create image/video posts
• createCarouselPost - Multi-media carousels
• createReel - Short-form videos
• publishPost - Publish created content

Story Operations (NEW):

• createStory - Create and publish stories

Media Operations (NEW):

• listMedia - Get your media list
• getMedia - Get media details
• getMediaChildren - Get carousel children

User Operations:

• getUserProfile - Fetch user information
• getMyProfile - Get authenticated account info

Webhook Events:

• messages - Incoming messages
• messaging_postbacks - Button interactions
• messaging_optins - Consent events

� Token Management (v1.5.0+)

Automatic Long-Lived Token System

Instagram uses a two-tier token system that this package automatically manages for you:

Token Type	Validity	Management
Short-lived	1 hour	Received from OAuth
Long-lived	60 days	Auto-exchanged on first use
Refreshed	60 days	Auto-refreshed before expiration

How It Works

OAuth Authentication (User action)
         ↓
Short-lived Token (1 hour)
         ↓
First API Call (automatic)
         ↓
Long-lived Token Exchange (automatic)
         ↓
Token Valid for 60 Days
         ↓
Auto-refresh at 53 Days (automatic)
         ↓
Another 60 Days of Validity

Key Features

✅ Zero Configuration - Everything happens automatically
✅ No More Errors - "refreshToken is required" error is eliminated
✅ Smart Refresh - Tokens refresh when at least 24 hours old and expiring within 7 days
✅ Fallback Protection - If refresh fails, attempts to exchange current OAuth token
✅ Secure Storage - All tokens encrypted in N8N credential system

Best Practices

• Keep Workflows Active: Run at least once every 50 days to maintain token validity
• Monitor Health: Create a weekly health-check workflow (optional)
• Handle Errors Gracefully: Use continueOnFail for robust error handling

Token Lifecycle Example

// Day 1: OAuth authentication
User authenticates → Short-lived token (expires in 1 hour)

// Day 1: First workflow run
First API call → Automatic exchange → Long-lived token (expires in 60 days)

// Day 53: Automatic refresh (7 days before expiry)
API call → Token check → Auto-refresh → New long-lived token (expires in 60 days)

// Repeat cycle every ~53 days as long as workflows are active

What If Token Expires?

If a workflow is inactive for 60+ days:

• Token expires and cannot be refreshed
• Workflow shows error: "Instagram access token has expired"
• Solution: Reconnect your Instagram OAuth2 credential (takes 30 seconds)

Learn More

📘 TOKEN_MANAGEMENT.md - Comprehensive token management guide
🔧 TOKEN_MANAGEMENT_IMPLEMENTATION.md - Technical implementation details

�🔧 Configuration

Webhook Setup

• In Meta App Dashboard → Instagram → Webhooks
• Subscribe to messages field
• Callback URL: Your n8n webhook URL

  https://your-n8n.com/webhook/instagram
  

• Verify Token: Enter in both Meta and n8n credentials
• Click Verify and Save

Rate Limits

• API Calls: 200 requests per hour per user
• Messages: 1000 characters max
• Buttons: 3 per template, 20 characters per title
• Quick Replies: 13 max per message
• Webhook Response: Must respond within 20 seconds

🛠️ Troubleshooting

Common Issues

"Invalid OAuth Access Token"

• Verify token hasn't expired
• Check required permissions are granted
• Regenerate token in Meta Developer Console

"Webhook Verification Failed"

• Ensure verify token matches in both Meta and n8n
• Check n8n webhook is publicly accessible via HTTPS
• Verify firewall allows Meta's IP ranges

"User Cannot Receive Messages"

• User must initiate conversation first (24-hour window)
• Use message tags for out-of-window messaging
• Verify Instagram Business Account is active

"Rate Limit Exceeded"

• Implement exponential backoff
• Reduce request frequency
• Use batch operations where possible

Debug Mode

Enable n8n debug logging:

export N8N_LOG_LEVEL=debug
n8n start

🤝 Support

Resources

• 📖 Instagram Graph API Documentation
• 💬 n8n Community Forum
• 🐛 Issue Tracker
• 📧 Email: [e-mail]

Contributing

Contributions are welcome! Please:

• Fork the repository
• Create a feature branch
• Follow existing code style
• Add tests for new features
• Submit a pull request

See CODE_OF_CONDUCT.md for guidelines.

📄 License

MIT License - see LICENSE.md for details.

Copyright © 2025 Mohammad Mahdi Samei

🙏 Acknowledgments

• Built with n8n - Fair-code workflow automation
• Powered by Instagram Graph API
• Icons by Instagram Brand Guidelines

📊 Stats

Made with ❤️ for the n8n community | GitHub | npm