@mookielianhd/n8n-nodes-instagram 2.2.0 → 2.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @mookielianhd/n8n-nodes-instagram
 
-This package adds an Instagram Publishing node to n8n so you can send media to your Instagram Business accounts without leaving your workflow.
+This package adds an Instagram node to n8n so you can publish media to your Instagram Business accounts, moderate comments, and send private replies — all from within your workflows.
 
-Instagram Publishing is powered by the Facebook Graph API and allows programmatic upload of images, reels and stories to any Instagram Business or Creator account.
+Instagram features are powered by the Facebook/Instagram Graph API and allow programmatic upload of images, reels and stories, plus comment moderation and private replies, for any Instagram Business or Creator account.
 
 [n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/sustainable-use-license/) workflow automation platform.
 
@@ -20,17 +20,28 @@ Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes
 
 ## Operations
 
-The node exposes three resources that follow the same two-step publish flow (media container creation + media publish):
+The node exposes several resources:
 
 | Resource | Description |
 | --- | --- |
-| `Image` | Publish a single image with an optional caption. |
-| `Reels` | Publish a reel video. Handles container polling until the video is processed. |
+| `Image` | Publish a single image with an optional caption. Uses the two-step container → publish flow. |
+| `Reels` | Publish a reel video. Handles container polling until the video is processed before publishing. |
 | `Stories` | Publish a story video using the same logic as reels with `media_type=STORIES`. |
+| `Comments` | List comments on media, hide/unhide or delete individual comments, disable/enable comments on media, and send **private replies** to commenters. |
+| `IG User` | Read basic profile data for an Instagram Business/Creator account and list its media using the IG User Graph API. |
+| `IG Hashtag` | Search for hashtags by name and fetch top or recent media for a hashtag with paging and limit/return-all support. |
+| `Messaging` | Send direct messages (DMs) to Instagram users via the Instagram Messaging API. |
+| `Auth` | Exchange short-lived Instagram User tokens for long-lived tokens, refresh long-lived tokens, and call the Graph API `/me` endpoint. |
 
 ## Credentials
 
-Create an **Instagram API** credential that stores a long-lived Facebook Graph API user access token with `instagram_basic`, `pages_show_list`, `instagram_content_publish`, and `pages_read_engagement` permissions.  
+Create an **Instagram API** credential that stores a long-lived Facebook Graph API user access token with at least:
+
+* `instagram_basic`
+* `pages_show_list`
+* `instagram_content_publish`
+* `pages_read_engagement`
+* `instagram_manage_comments` (or `instagram_business_manage_comments` if using Instagram Login)
 Steps:
 
 1. Make sure the Instagram account is a Business/Creator account connected to a Facebook Page.  
@@ -40,25 +51,105 @@ Steps:
 
 ## Compatibility
 
-- Built against **n8n 1.120.4** (community-node CLI v0.16).  
-- Requires n8n `>=1.0` with community nodes enabled.  
+- Built and tested against **n8n 2.6.3** (community-node CLI v0.16).  
+- Requires n8n `>=1.0` with community nodes enabled (recommended `>=2.x`).  
 - Uses only built-in n8n dependencies, so it is Cloud-compatible.
 
 ## Usage
 
-1. Add the **Instagram** node to your workflow and select one of the resources (Image/Reels/Stories).  
-2. Provide the Instagram Business Account ID (the “Node” parameter), media URL and caption.  
+### Publishing media (Image / Reels / Stories)
+
+1. Add the **Instagram** node to your workflow and select one of the resources (`Image` / `Reels` / `Stories`).  
+2. Provide the Instagram Business Account ID (the `Node` parameter), media URL and caption.  
 3. The node first creates the media container, polls Graph API until processing completes, then triggers `media_publish`.  
-4. Handle any errors returned by the API (rate limits, permissions) via the node’s error output or `Continue On Fail`.
+4. Handle any errors returned by the API (rate limits, permissions, validation) via the node’s error output or `Continue On Fail`.
+
+### Comment moderation and private replies (Comments)
+
+1. Add the **Instagram** node and set **Resource** to `Comments`.  
+2. Choose an **Operation**:
+   - `List` – fetch comments for a given media ID.  
+   - `Hide` / `Unhide` / `Delete` – moderate a specific comment by its comment ID.  
+   - `Disable Comments` / `Enable Comments` – toggle comments on a media object by its media ID.  
+   - `Send Private Reply` – send a private reply message to a commenter using their comment ID.  
+3. Provide the required IDs:
+   - `Media ID` for listing comments or enabling/disabling comments.  
+   - `Comment ID` for hide/unhide/delete/private reply operations.  
+4. For **Send Private Reply**, also fill in:
+   - `Node` – the Instagram professional account ID that owns the commented media.  
+   - `Message` – the private reply text that will be sent to the commenter’s inbox/request folder (subject to the 7‑day and messaging window rules defined by Meta).  
+
+### Reading IG User profile and media (IG User)
+
+1. Add the **Instagram** node and set **Resource** to `IG User`.  
+2. Choose an **Operation**:
+   - `Get` – fetch basic profile information for an Instagram Business/Creator account (username, name, bio, website, media_count, followers/follows, profile picture URL).  
+   - `Get Media` – list media owned by that account, including media type, URLs, caption, permalink, timestamp and username.  
+3. Provide:
+   - `Node` – the IG User ID of the professional account you want to read (or `me` if your credential token belongs to that account).  
+   - `Graph API Version` – the Graph version to use (for example `v24.0`).  
+
+### Searching hashtags and fetching hashtag media (IG Hashtag)
+
+1. Add the **Instagram** node and set **Resource** to `IG Hashtag`.  
+2. Choose an **Operation**:
+   - `Search` – look up a hashtag by name and get its global hashtag ID.  
+   - `Get Recent Media` – get the most recently published media tagged with a hashtag.  
+   - `Get Top Media` – get the most popular media tagged with a hashtag.  
+3. For **Search**, provide:
+   - `Node` – the IG User ID performing the query.  
+   - `Hashtag Name` – the hashtag name, without `#`.  
+4. For **Get Recent Media** / **Get Top Media**, provide:
+   - `Node` – the IG User ID performing the query.  
+   - `Hashtag ID` – the ID returned from the search operation.  
+   - `Return All` / `Limit` – choose whether to fetch all available media (within a safety cap) or only up to a limit.  
+
+### Sending direct messages (Messaging)
+
+1. Add the **Instagram** node and set **Resource** to `Messaging`.  
+2. Choose **Operation** `Send Message`.  
+3. Provide:
+   - `Node` – the IG professional account ID that will send the message.  
+   - `Graph API Version` – the Graph version to use (for example `v24.0`).  
+   - `Recipient IG User ID` – the Instagram-scoped user ID (IGSID) of the recipient, typically obtained from Messaging webhook events.  
+   - `Message Text` – the text body of the direct message.  
+
+### Token exchange, refresh and `/me` (Auth)
+
+1. Add the **Instagram** node and set **Resource** to `Auth`.  
+2. Choose an **Operation**:
+   - `Exchange Access Token` – exchange a **short-lived** Instagram User access token for a **long-lived** token.  
+   - `Refresh Access Token` – refresh an existing long-lived token using the Instagram Platform refresh endpoint.  
+   - `Get Me` – call the Graph API `/me` endpoint using the `instagramApi` credential’s access token.  
+3. For **Exchange Access Token**, provide:
+   - `Short-Lived Access Token` – the short-lived token from your login flow.  
+   - `App Secret` – the Instagram App Secret from your Meta App Dashboard.  
+4. For **Refresh Access Token**, optionally provide:
+   - `Access Token` – the long-lived token to refresh. Leave empty to use the token from the credential.  
+5. For **Get Me**, provide:
+   - `Graph API Version` – the Graph version to use (for example `v24.0`). The node will read `/me` using the credential’s token.  
 
 ## Resources
 
 * [n8n community nodes documentation](https://docs.n8n.io/integrations/#community-nodes)  
 * [Instagram Graph API - Publishing](https://developers.facebook.com/docs/instagram-api/reference/ig-user/media)  
-* [Video/Reels publishing guide](https://developers.facebook.com/docs/instagram-api/guides/content-publishing/reels/)
+* [Video/Reels publishing guide](https://developers.facebook.com/docs/instagram-api/guides/content-publishing/reels/)  
+* [Comment Moderation](https://developers.facebook.com/docs/instagram-platform/comment-moderation)  
+* [Private Replies](https://developers.facebook.com/docs/instagram-platform/private-replies)  
+* [IG User](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user)  
+* [IG Hashtag Search](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-hashtag-search/)  
+* [IG Hashtag Recent Media](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-hashtag/recent-media/)  
+* [IG Hashtag Top Media](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-hashtag/top-media/)  
+* [Instagram Messaging API](https://developers.facebook.com/docs/messenger-platform/instagram/features/)  
+* [Instagram Platform Access Token](https://developers.facebook.com/docs/instagram-platform/reference/access_token/)  
+* [Instagram Platform Refresh Access Token](https://developers.facebook.com/docs/instagram-platform/reference/refresh_access_token/)  
+* [Instagram Platform /me](https://developers.facebook.com/docs/instagram-platform/reference/me/)
 
 ## Version history
 
 | Version | Notes |
 | --- | --- |
+| 2.3.0 | Upcoming: Adds `Comments` resource with comment moderation (list/hide/unhide/delete, enable/disable comments) and **Private Replies** support, an `IG User` resource for reading profile data and listing media, `IG Hashtag` resource for hashtag search and hashtag media, `Messaging` resource for sending DMs, and `Auth` helpers for access token exchange/refresh and `/me`. |
+| 2.2.0 | Improved publishing UX, adds alt text, location ID, user tags, and product tags support for media publishing. |
+| 2.1.0 | Stable release of Instagram publishing (Image/Reels/Stories) using the container → publish flow with robust polling and error handling. |
 | 0.1.0 | Initial release with Image, Reels and Stories publishing & built-in container polling. |