npm package: @pakoor/n8n-nodes-instagram
Description: n8n community node for Instagram Messaging API integration
Latest version: 0.2.0

# 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

```bash
npm install n8n-nodes-instagram
```

Or in your n8n installation directory:

```bash
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](https://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

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

### Send Button Template

```json
{
  "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

```json
// 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.

```json
[
  {
    "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:

```json
{
  "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

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint
```

## License

MIT

## Links

- [Instagram Graph API Documentation](https://developers.facebook.com/docs/instagram-api)
- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)
- [Meta Developer Portal](https://developers.facebook.com)