Instagram integration

What it does

Connect an Instagram professional account and run it from a workflow: publish photos, Reels, Stories and carousels, read post and account insights, moderate comments, and reply to direct messages. Each client connects their own Instagram account, so you never hold their password and their data stays walled off from your other clients.

This integration uses Business Login for Instagram. Your clients do not need a Facebook Page — they connect their Instagram account directly.

Connect an Instagram account

The account must be an Instagram Business or Creator account. A personal account cannot be connected; switching is free and takes a minute in the Instagram app under Settings → Account type and tools.

Create a Meta app at developers.facebook.com and add the Instagram product with API setup with Instagram login.
Register your redirect URI: https://<your-domain>/oauth/callback.
Add your Instagram app ID and secret as your own app keys in TaskJuice under Apps → Instagram, in the Your own OAuth app section. The consent screen your clients see then carries your brand, not ours.
Add the connection from the node that needs it and complete the Instagram authorization.

Access levels — read this before you promise a client comment or DM automation

Meta gates the two most useful permissions behind App Review plus Business Verification:

Permission	What Standard Access gives you	What you need for the real thing
`instagram_business_basic`	Full profile and media reads	Nothing extra
`instagram_business_content_publish`	Publishing works	Nothing extra
`instagram_business_manage_insights`	Insights work	Nothing extra
`instagram_business_manage_comments`	Replies, hide and delete work; List Comments is empty	Advanced Access for reads and the comment webhooks
`instagram_business_manage_messages`	Empty results	Advanced Access

The failure mode is quiet and worth knowing: with Standard Access, List Comments and List Conversations return HTTP 200 with an empty list rather than an error, even while the post's own comments_count reports a non-zero total. Nothing looks broken. If those actions return nothing on a post you can see comments on, you are on Standard Access and need App Review, not a bug report.

Triggers

Seven, delivered as Meta webhooks. They arrive at a single callback URL you configure once on your own Meta app, and the platform splits each delivery into individual events. You can connect several Instagram accounts. Each event names its account (entry[].id) and starts only the workflows that use that account's connection. An event for an account no connection has recorded yet goes to the workflows of the first Instagram connection that subscribed; reconnect a connection to record its account.

Trigger	Fires when
Comment Received	Someone comments on your media, or @-mentions you in a comment
Live Comment Received	Someone comments on your active live broadcast
Direct Message Received	Someone sends your account a DM
Message Reaction Received	Someone reacts to a message, or removes a reaction
Message Button Tapped	Someone taps an icebreaker or call-to-action button
Message Referral Received	Someone opens a conversation through an `ig.me` link carrying a `ref`
Message Seen	The other participant reads a message you sent

Comment Received carries the comment itself — text, from.username and the media id are all in the payload, so you do not need a follow-up read to act on it.

sender.id on a message is Instagram-scoped, meaning it is unique to your app rather than a public account id. It is exactly what Send Direct Message expects, so you can wire it straight through to a reply.

Setting webhooks up

In your Meta app dashboard, open the Instagram use case and find Configure webhooks.
Paste your account's Instagram callback URL — shown as Callback URL on any Instagram trigger node — as Meta's Callback URL. For the Verify token, enter any value: TaskJuice completes Meta's verification handshake on your unique callback URL, so the token itself is not checked.
Subscribe the app to comments, live_comments, messages, message_reactions, messaging_postbacks, messaging_referral and messaging_seen — the fields behind the seven triggers. That is the app-level half. The per-account half is automatic: when you publish a workflow with an Instagram trigger, TaskJuice opts the connected account in (POST /me/subscribed_apps) to exactly the fields your published workflows use, and keeps that list current as workflows change. Meta requires this call for every account, or nothing is delivered.
Back in TaskJuice, open Apps → Instagram and paste your Instagram app secret into the Instagram app secret field, below the OAuth client secret. It is the same value as the client secret, from Instagram → API setup with Instagram login. Meta signs Instagram webhooks with this secret, not with the parent Meta app's App Secret under App settings → Basic — that one fails verification.
Publish a workflow that starts with an Instagram trigger, then use the Test button beside the matching subscribed field in the Meta dashboard. The test delivery appears on Monitoring → Activity as a Delivery marked "nothing to route": Meta's test payload is a bare sample without the account envelope, so it verifies but starts no run. If it appears as Auth failed instead, the secret in step 4 is wrong. Publish first — a test sent before any Instagram workflow is published has nothing to attach to and shows nowhere.
Under App settings → Basic, fill in Privacy Policy URL and User data deletion, choosing Data deletion instructions URL. Meta requires both before the app can go live. If you have no pages of your own you may use https://taskjuice.ai/legal/privacy-policy and https://taskjuice.ai/legal/data-deletion; the latter is written for exactly this use, see Data Deletion Requests.

Step 4 is not optional if you want triggers. Meta signs every webhook with your Instagram app secret, and TaskJuice refuses deliveries it cannot verify. Skip it, or paste the parent Meta app's secret by mistake, and your actions keep working while every trigger delivery lands on Monitoring → Activity as Auth failed and never runs. It lives on the app's page under Your own OAuth app, not on a connection, because one key governs verification for every workspace in the account.

Your app must be in published state to receive webhooks at all. Meta says so directly on that dashboard page. Until App Review completes, the callback URL will verify but no events will arrive — the same gate that limits comment and DM reads.

Disconnecting stops deliveries. Meta offers no per-account unsubscribe on Instagram Login, so TaskJuice releases the subscription on its side when you unpublish or disconnect; Meta's own token revocation ends deliveries for a removed account, and anything that still arrives for an account with no subscription is refused at the door.

Actions

Account and media

Get Account — profile, follower and media counts. A good connection check.
List Media — published posts, newest first, cursor-paginated.
Get Media — one post by ID.
List Carousel Children — the individual items inside an album.
List Stories — stories published in the last 24 hours.
List Tagged Media — posts by other accounts that tag this one.

Insights

Get Account Insights — reach, follower count and other account metrics.
Get Media Insights — reach, likes, comments, saves and shares for one post.
Get Publishing Limit — quota_usage against quota_total for the rolling 24-hour publishing quota.

Publishing — always two steps: stage a container, then publish it.

Create Image Container, Create Reel Container, Create Story Container, Create Carousel Image Item, Create Carousel Video Item, Create Carousel Container — stage media. Nothing is public yet. Carousel items are split by type because Meta requires media_type=VIDEO on a video item and rejects it on an image.
Get Container Status — poll until FINISHED. Video and Reel processing is asynchronous; publishing early fails.
Publish Container — makes the post live. This is public immediately and counts against the quota.

Comments (needs Advanced Access to read)

List Comments, Get Comment, List Comment Replies — read.
Create Comment, Reply To Comment — post publicly as the account.
Hide Comment / Unhide Comment — moderation, reversible.
Delete Comment — permanent.
Set Comments Enabled — turn commenting on or off for one post. Reversible.
Reply To Mention — comment on someone else's post that @-mentions you, using the ids from Comment Received.

Direct messages (needs Advanced Access to read)

List Conversations, Get Conversation Messages, Get Message — read the inbox.
Send Direct Message, Send Image Direct Message, Send Media Direct Message (audio, video or file) — reply to a customer. Images are separate because Meta accepts them in a different request shape.
Send Private Reply — one DM to the author of a comment, within 7 days of the comment. Meta allows a single private reply per comment.
React To Message — add or remove an emoji reaction.
Get User Profile — name, username, profile picture and follow relationship for someone who has messaged you. Resolves the sender.id a message trigger delivers.
Send Typing Indicator Or Mark Seen — acknowledge a message while a longer workflow runs.

Known limitations

Publishing quota: 100 posts per rolling 24 hours per account. Check Get Publishing Limit before a bulk run.
The 24-hour messaging window: Instagram only allows a reply within 24 hours of the user's last message unless a message tag applies.
Media URLs must be publicly reachable. Instagram fetches them server-side, so a signed or firewalled URL fails.
A missing object never returns 404. Depending on the endpoint it answers HTTP 400 with a does not exist message, or HTTP 500 with a body claiming is_transient: true. A wrong media or comment ID can therefore look like a server fault rather than a bad reference.
An expired or invalid token returns HTTP 400, not 401.
Comments and messages are 24-hour-window and access-level sensitive — see the access-level table above.
Four webhook fields are not offered: message_echoes, messaging_optins, messaging_handover and standby appear on Meta's Instagram Login field list, but Meta publishes no payload example for any of them, so their event shape is unknown. We would rather ship nothing than ship a trigger that silently never fires.
No Facebook Page features. Hashtag search, business_discovery and product tagging belong to the Facebook Login product and are not reachable through Business Login for Instagram.