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)

1. Go to Settings > Community Nodes
2. Select Install
3. 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)

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

Access Token

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

2. Create Your First Workflow

1. Add an Instagram node to your workflow
2. Select your credentials
3. Choose a resource and operation
4. Configure the parameters
5. 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:

1. Deploy your n8n instance with a public URL
2. Add the Instagram Trigger node to a workflow
3. Activate the workflow
4. 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