metaflow

Metaflow is a production-ready Meta platform automation toolkit for n8n. Publish and manage content across Instagram, Facebook, and Threads via Meta's Graph APIs—moderate comments, send messages, search hashtags, manage tokens, and react to real-time webh

Documentation

Publish

metaflow @0m4r/n8n-nodes-metaflow


Metaflow is a production-ready Meta platform automation toolkit for n8n. Publish and manage content across Meta platforms (Instagram, Facebook, Threads) via Meta's Graph APIs—moderate comments, send messages, search hashtags, manage tokens, and react to real-time webhook events.


Current state: Metaflow currently supports Instagram and Facebook Graph API operations. Threads and additional Meta platforms are planned for future releases. The node, credentials, and documentation are written to accommodate the broader Meta platform scope as new capabilities are added.

This package’s Metaflow nodes for n8n let you publish and manage content, moderate comments, send messages, and react to real-time events across Meta platforms via Meta's Graph APIs.

All functionality is built on Meta's Graph API, including media publishing (images, Reels, Stories, carousels), comment moderation, private replies, messaging, hashtag search, IG User/Page helpers, and webhook-based triggers.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources
Version history

Installation

The npm package name is @0m4r/n8n-nodes-metaflow. On a self-hosted n8n instance, install it from Settings → Community nodes or use n8n's manual installation instructions. Unverified community nodes require self-hosting; n8n Cloud only makes verified community nodes available.

Operations

The node exposes several resources:

Resource Description
Image Publish a single image with an optional caption. Uses the two-step container → publish flow. Supports alt text, location, user tags, and product tags.
Reels Publish a reel video. Handles container polling until the video is processed before publishing. Supports product tags and Trial Reels via trial_params.
Stories Publish a story video using the same logic as reels with media_type=STORIES.
Carousel Publish a carousel (album) post with up to 10 images and/or videos. The node creates child containers, builds a carousel container, waits for it to be ready, then publishes it. Includes detailed per-item error reporting and progress messages.
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 cursor pagination and limit/return-all support.
Messaging Send direct messages (DMs) via Meta Messaging APIs.
Page Given a Facebook Page ID, fetch the connected Instagram Business/Creator account (instagram_business_account).
Auth Exchange short-lived Meta access tokens for long-lived tokens, refresh long-lived tokens, and call the Graph API /me endpoint.
Meta Trigger Trigger: receive real-time webhook events from Meta (comments, messages, mentions, story insights, etc.) and run a workflow for each event. Requires a separate Meta Webhook credential (App Secret) and Meta App Dashboard webhook configuration.

Credentials

Create a Metaflow Meta API credential and provide a token issued for the selected Meta API setup. The endpoint setting chooses the Graph API host; it does not convert a token or grant permissions.

For Instagram Login (graph.instagram.com), use an Instagram User access token with:

  • instagram_business_basic
  • instagram_business_content_publish
  • instagram_business_manage_comments
  • instagram_business_manage_messages

For Facebook Login (graph.facebook.com), use a Facebook User or Page access token with the permissions required by the operations you use. A typical setup includes:

  • instagram_basic
  • pages_show_list
  • instagram_content_publish
  • pages_read_engagement
  • instagram_manage_comments
  • instagram_manage_messages
  • pages_messaging (for Facebook Login messaging)
  • pages_manage_metadata (for webhook subscriptions)

Steps:

  1. Make sure the Instagram account is a Business/Creator (professional) account. A linked Facebook Page is required for Facebook Login/Page-token operations, but is not a general requirement for Instagram Login.
  2. Use Meta's Graph Explorer or your own app to generate an access token that includes the scopes listed above.
  3. Convert it to a long-lived token and paste it into the credential's Access Token field.
  4. Select API Endpoint: Choose the host that matches the token:
    • Instagram Graph API (graph.instagram.com) - default; use with an Instagram User token from Instagram Login.
    • Facebook Graph API (graph.facebook.com) - use with a Facebook User or Page token from Facebook Login.
  5. The built-in credential test uses v26.0 to confirm the token works.

Changing the endpoint does not convert your token, change its login flow, or grant permissions. Use the token type and permissions required by the selected Meta login flow and operation. Both API setups support content publishing and comment moderation. Facebook Login is required for Page lookup and hashtag search; product tagging is available through the Facebook Login setup. Stories can only be published to eligible Business accounts. The Auth token exchange and refresh operations use Instagram Login endpoints and Instagram User tokens.

For the full operation-by-operation permission matrix and access requirements, see Meta's Instagram Platform overview, content publishing requirements, and webhook field permissions.

Note on Messaging: The Instagram Messaging API (Send Message and Send Private Reply) supports two host URLs depending on your credential's API Endpoint setting:

  • Instagram Graph API (graph.instagram.com) - Use with Instagram Login access token
  • Facebook Graph API (graph.facebook.com) - Use with Facebook Page access token

The node uses the host URL selected in your credential. The default is graph.instagram.com.

Important: You must use the correct access token type for your chosen API endpoint:

See Meta's Send a Private Reply to a Commenter and Instagram Send API reference for more details.

Meta Webhook Trigger credentials

For the Meta Trigger node, create a Metaflow Meta Webhook API credential and enter the Meta App Secret (App Dashboard → Settings → Basic). Signature verification is enabled by default and checks X-Hub-Signature-256 against the raw request body. The Verify Token is set in the node parameters and must match the value entered in the Meta App Dashboard for the callback URL. Disable signature verification only for a trusted test environment. Existing workflows may have the previous skip-verification setting saved; set it to false and update the old webhook credential with the App Secret.

Meta Webhook Trigger

The Meta Trigger receives Meta webhook notifications and starts a workflow for each included event. For direct messages with Instagram Login (graph.instagram.com), follow Meta's Instagram Platform Webhooks setup. This flow uses an Instagram User access token to subscribe the professional account to webhook fields; it does not use a Facebook Page access token.

Requirements

  • The Instagram account must be a Business or Creator (professional) account, and must authorize your app.
  • For Instagram Login, request instagram_business_basic and instagram_business_manage_messages to receive the messages field. The app needs Advanced Access for production use and the business must be verified. The app must be Live/published to receive notifications from app users; in development, delivery is limited to eligible app roles/testers.
  • Meta must be able to reach the callback URL over HTTPS with a valid TLS certificate. Self-signed certificates are not supported.
  • Subscribe to fields in both places: select them for your app in the Meta App Dashboard, then enable notifications on each Instagram professional account using that account's token. Account subscription applies the fields selected for the app; it does not select a different field set per account.

The trigger can filter comments, live_comments, message_echoes, messaging_reactions, messages, mentions, messaging_handover, messaging_referrals, messaging_optins, messaging_seen, messaging_postbacks, and standby. story_insights is also available with Facebook Login. Meta's supported fields and permissions depend on the API setup; check the Instagram Webhooks field and permission matrix before subscribing.

Setup

  1. Configure the trigger in n8n
    Add the Meta Trigger node. Set Verify Token to a random string; you will enter the same value in Meta. Add a Metaflow Meta Webhook API credential containing your Meta App Secret (App Dashboard → App settings → Basic). The App Secret is used to validate webhook signatures; it is not an access token.

  2. Configure the app-level callback and fields in Meta
    In the Meta App Dashboard, open your Instagram API setup's Webhooks configuration. Add the n8n callback URL and the matching Verify Token. Use the Production URL for an active workflow, or the Test URL while the workflow is listening for a test event. Verify the callback, then subscribe the app to messages (and any other fields you need).

  3. Enable notifications on each Instagram account
    For Instagram Login, make a POST to the professional account's subscribed_apps edge using its Instagram User access token. Set subscribed_fields to the fields selected for the app. For example, to receive DMs:

    curl -i -X POST \
      "https://graph.instagram.com/v{api-version}/{IG_USER_ID}/subscribed_apps" \
      -d "subscribed_fields=messages" \
      -d "access_token={INSTAGRAM_USER_ACCESS_TOKEN}"
    

    A successful response is {"success":true}. Use the supported Graph API version for your app. Do not use an Instagram User access token with graph.facebook.com, or a Facebook/Page token with graph.instagram.com. For Unified Login or Facebook Login, use the matching host, account/Page ID, token type, and permissions in Meta's setup guide.

  4. Optional: filter events
    Use Events to Include to pass only selected event types (for DMs, include messages). If left empty, all received event types are output. This filter only affects events after Meta has delivered them; it does not create Meta subscriptions.

Meta verifies the callback with a GET request containing hub.mode, hub.verify_token, and hub.challenge; the node checks the token and returns the challenge. For POST notifications, Meta signs the raw JSON body with the app secret and sends X-Hub-Signature-256. The node validates this signature by default and responds to accepted events with HTTP 200. Meta retries failed deliveries, so keep signature verification enabled and avoid slow downstream work before acknowledging events.

Each accepted event is output as an item with object, field, value, id, time, and the event payload. Use the Metaflow node (for example, Messaging or Comments) in the same workflow to act on it.

Compatibility

  • Development and CI use n8n-workflow 2.41.2 as the build and typecheck target. This records the tested development dependency; it isn't a claim that this is the latest n8n release.
  • Declares a peer dependency on n8n-workflow * as required by n8n's strict community-node linter. Compatibility with earlier workflow versions is not verified.
  • Requires n8n with community nodes enabled.
  • The runtime package has no third-party production dependencies. n8n Cloud availability depends on n8n verification; unverified community nodes must be installed on a self-hosted instance.

Usage

Publishing media (Image / Reels / Stories)

  1. Add the Instagram node to your workflow and select one of the resources (Image / Reels / Stories).
  2. Provide:
    • Account: Select your Instagram account from the dropdown or enter the IG User ID manually
    • Graph API Version: defaults to v26.0; select a version currently supported by Meta for the operation.
    • Media URL: a public URL Meta can fetch. The node does not upload n8n binary data directly. Feed images and Reels accept an optional Caption; Stories do not.
  3. Add optional fields only where supported: alt text for feed images and carousel image slides; location tags for feed images, Reels, and carousels; product tags for feed images and Reels (up to 20 per post) and carousel slides (up to 5 per slide and 20 per carousel), using Facebook Login; user tags for images, Reels, Stories, and carousel image slides; collaborators for feed images, Reels, and carousels. Cover/audio/thumbnail/Trial Reel settings are Reels-only; share-to-feed is available for Reels and carousels.
  4. The node first creates the media container, polls Graph API until processing completes, then triggers media_publish.
  5. For long-running uploads (large videos), the node uses robust polling and retry logic and surfaces progress via the n8n execution logs (for example, when publishing Reels or Trial Reels).
  6. Handle any errors returned by the API (rate limits, permissions, validation) via the node's error output or Continue On Fail.

Publishing carousel posts (Carousel)

  1. Add the Instagram node and set Resource to Carousel, Operation to Publish.
  2. Provide:
    • Account – Select your Instagram account from the list (loaded automatically) or enter the IG User ID manually
    • Graph API Version – defaults to v26.0; select a version currently supported by Meta for the operation.
    • Caption – optional caption for the published carousel.
    • Carousel Media – 2–10 items, each with:
      • Media Type – Image or Video.
      • Image URL or Video URL – public URLs Meta can fetch.
      • For image slides, optional Alt Text and User Tags; carousel slides may have up to 5 Product Tags each (20 total per carousel, using Facebook Login).
    • Additional Fields → Collaborators – optional, up to 3 Instagram usernames.
  3. The node:
    • Creates one child container per image/video (is_carousel_item=true for each).
    • Waits for each child container to become ready.
    • Creates a carousel container (media_type=CAROUSEL, children=<child_ids>) with the caption.
    • Waits for the carousel container to be ready, then calls /{ig-user-id}/media_publish.
  4. Errors during any step are annotated with which child item failed (for example, “Carousel item 3 (video)…”), making it easier to debug problematic URLs.

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 – defaults to v26.0; select a version currently supported by Meta for the operation.

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 follow all pages returned by Meta or stop at the configured limit. The default limit is 50; the limit field accepts values from 1 to 500.

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 – defaults to v26.0; select a version currently supported by Meta for the operation.
    • 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.

The recipient must have initiated a conversation with the professional account; the Messaging API does not send first-contact DMs to arbitrary usernames. The recipient IGSID is required by Meta. See the Instagram Messaging API.

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 metaflowApi 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 the Graph API Version. The request uses the host selected in the credential and the access token stored in that credential.

Getting the Instagram account for a Facebook Page (Page)

  1. Add the Instagram node and set Resource to Page, Operation to Get Instagram Account.
  2. Provide:
    • Graph API Version – defaults to v26.0; select a version currently supported by Meta for the operation.
    • Page ID – the Facebook Page ID that is linked to your Instagram professional account.
  3. The node calls:
    • GET /{page-id}?fields=instagram_business_account
      and returns the instagram_business_account object (including the Instagram User ID) so you can feed it into other resources (Image/Reels/Stories/Carousel/IG User).

Trial Reels (Reels with trial_params)

  1. Add the Instagram node and set Resource to Reels, Operation to Publish.
  2. Under Additional Fields, set Trial Reel – Graduation Strategy:
    • MANUAL – you will decide in the Instagram app when (or if) to graduate the trial reel.
    • SS_PERFORMANCE – Instagram will automatically graduate the trial reel if it performs well.
  3. The node sends a trial_params JSON object in the create-container request, as documented in the IG User Media reference.

Resources

Version history

See CHANGELOG.md

Discussion