@pakoor/n8n-nodes-instagram

n8n-nodes-instagram

n8n community node for Instagram Messaging API integration. This package provides OAuth2/Access Token authentication, messaging capabilities, content publishing, comment management, and webhook-based event handling through the Instagram Graph API.

Features

• OAuth2 & Access Token Authentication - Secure connection with automatic token refresh
• Messaging - Send text, images, audio, video, buttons, carousels, and quick replies
• User Management - Retrieve user profiles and account information
• Comment Management - Get, reply, delete, and moderate comments
• Content Publishing - Create posts, carousels, stories, and reels
• Media Management - List and retrieve media details
• Webhook Triggers - Receive real-time messaging and content events

Installation

Community Nodes (Recommended)

• Go to Settings > Community Nodes
• Select Install
• Enter n8n-nodes-instagram and confirm

Manual Installation

npm install n8n-nodes-instagram

Or in your n8n installation directory:

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

Prerequisites

• Instagram Business Account or Creator Account
• Facebook Page connected to your Instagram account
• Meta Developer App with Instagram Graph API enabled

Required Permissions

• instagram_basic - Basic account information
• instagram_manage_messages - Send and receive messages
• instagram_manage_comments - Manage comments
• instagram_content_publish - Publish content
• pages_show_list - Access connected Facebook pages
• pages_read_engagement - Read page engagement data

Quick Start

1. Set Up Credentials

OAuth2 (Recommended)

• Create a Meta Developer App at developers.facebook.com
• Add Instagram Graph API product
• In n8n, create new Instagram OAuth2 API credentials
• Enter your App ID and App Secret
• Click Connect to authorize

Access Token

• Generate a long-lived access token from Meta Developer Console
• In n8n, create new Instagram Access Token API credentials
• Paste your access token
• Account ID will be auto-discovered

2. Create Your First Workflow

• Add an Instagram node to your workflow
• Select your credentials
• Choose a resource and operation
• Configure the parameters
• Execute the workflow

Node Operations

Instagram Node

Message Operations

Operation	Description
Send Text	Send a text message to a user
Send Image	Send an image message via URL
Send Audio	Send an audio message via URL
Send Video	Send a video message via URL
Send Button Template	Send interactive buttons
Send Generic Template	Send a carousel of cards
Send Quick Replies	Send quick reply options

User Operations

Operation	Description
Get Profile	Get a user's profile by IGSID
Get My Profile	Get your Instagram Business Account info

Comment Operations

Operation	Description
Get Comments	Get comments on a media post
Get Replies	Get replies to a comment
Reply	Post a public reply to a comment
Send Private Reply	Send a DM to a commenter (within 7 days)
Delete	Delete a comment
Toggle Visibility	Hide or unhide a comment

Post Operations

Operation	Description
Create Single	Create a single image/video post
Create Carousel	Create a carousel post (2-10 items)
Publish	Publish a media container

Story Operations

Operation	Description
Create	Create a story (image or video)

Reel Operations

Operation	Description
Create	Create a reel (video up to 60 seconds)

Media Operations

Operation	Description
List	List your media with pagination
Get	Get details of a specific media
Get Children	Get items in a carousel post

Instagram Trigger Node

Receives webhook events from Instagram with dual outputs:

Output	Events
Messaging Events	Messages, Postbacks, Opt-ins
Content Events	Comments, Mentions

Usage Examples

Send a Text Message

{
  "resource": "message",
  "operation": "sendText",
  "recipientId": "{{$json.sender_id}}",
  "text": "Hello! Thanks for reaching out."
}

Send Button Template

{
  "resource": "message",
  "operation": "sendButtonTemplate",
  "recipientId": "{{$json.sender_id}}",
  "text": "How can I help you?",
  "buttons": [
    { "type": "postback", "title": "View Products", "payload": "PRODUCTS" },
    { "type": "web_url", "title": "Visit Website", "url": "https://example.com" }
  ]
}

Create and Publish a Post

// Step 1: Create container
{
  "resource": "post",
  "operation": "createSingle",
  "mediaType": "IMAGE",
  "mediaUrl": "https://example.com/image.jpg",
  "caption": "Check out our new product! #newproduct"
}

// Step 2: Publish (use container ID from step 1)
{
  "resource": "post",
  "operation": "publish",
  "containerId": "{{$json.id}}"
}

Create Carousel Post (JSON/Expression)

When using the Create Carousel operation with Input Mode set to JSON / Expression, use the following array format for the Carousel Items (JSON) field. This is useful when mapping data from previous nodes.

[
  {
    "mediaType": "IMAGE",
    "mediaUrl": "https://example.com/image1.jpg",
    "userTags": "username1,username2" // Optional: Comma-separated usernames
  },
  {
    "mediaType": "VIDEO",
    "mediaUrl": "https://example.com/video1.mp4"
  },
  {
    "mediaType": "IMAGE",
    "mediaUrl": "https://example.com/image2.jpg"
  }
]

Note:

• mediaType: Must be IMAGE or VIDEO.
• mediaUrl: Must be a valid, public HTTPS URL.
• userTags: (Optional) Users will be tagged automatically on the image.
• Limit: 2 to 10 items per carousel.

Reply to Comments Automatically

Use the Instagram Trigger to receive comment events, then reply:

{
  "resource": "comment",
  "operation": "reply",
  "commentId": "{{$json.id}}",
  "message": "Thanks for your comment! 🙏"
}

Validation Limits

Field	Limit
Text message	1000 characters
Button count	3 maximum
Button title	20 characters
Quick replies	13 maximum
Carousel items	2-10 items
User tags	20 maximum
Tag position (x, y)	0-1 range
Reel duration	60 seconds

Webhook Setup

To use the Instagram Trigger node:

• Deploy your n8n instance with a public URL
• Add the Instagram Trigger node to a workflow
• Activate the workflow
• Configure the webhook URL in your Meta App:
  • Go to your Meta App > Webhooks
  • Subscribe to instagram webhooks
  • Enter your n8n webhook URL
  • Select events: messages, messaging_postbacks, comments, mentions

Error Handling

The node provides detailed error information:

Error Code	Description	Suggestion
4	Rate limit exceeded	Wait and retry
190	Invalid access token	Reconnect credentials
100	Invalid parameter	Check input values
10	Permission denied	Check app permissions

Enable Continue On Fail in node settings for graceful error handling in workflows.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

License

MIT

Links

• Instagram Graph API Documentation
• n8n Community Nodes
• Meta Developer Portal