Instagram tool

The Instagram tool lets an agent manage an Instagram Business or Creator account through the Graph API — publish image, carousel, reel, and story posts; read media and insights; and read, reply to, hide, and delete comments. It's a sibling of the Facebook tool: set it up once with an access token, then assign it to a bot.

What it can do

The agent chooses an action per call. Available actions:

• Publish — image, carousel, and reel posts (supply image_urls and/or video_url), plus publish_story.
• Read — list media, get a single media, and account & post insights.
• Comments — list, reply, hide/unhide, and delete.
• Manage — delete a media, and check the publishing quota.
• Discover — list_accounts returns each Page and its connected Instagram account id + username.

Configuration

The tool has four fields:

• Access token (required) — an access token with Instagram permissions. Stored encrypted and never shown again after saving. See How to get a token.
• Instagram account ID (optional) — the numeric account id. Set it to lock the configuration to one account; leave it blank to derive it from the Page or to pick an account per action.
• Facebook Page ID (optional) — the Page your Instagram account is connected to. The tool reads the Page's linked Instagram account, so you can set this instead of the account ID.
• API version (optional) — the Graph API version. Defaults to v25.0.

Eligibility

Before you can get a working token, the account has to be set up correctly:

1. Make the account Business or Creator. In the Instagram app: Settings → Account type and tools → Switch to professional account.
2. Connect it to a Facebook Page you admin (Instagram app → linked accounts, or via Meta Business Suite). The tool derives the Instagram account from this Page.
3. Have a Meta app with Instagram permissions enabled (add the Instagram product / a use case that includes Instagram) and admin rights on it. Standard Access is enough for your own accounts — no App Review.

How to get an access token

Required permissions

• instagram_basic — read the account & its media
• instagram_content_publish — publish posts / reels / stories
• instagram_manage_comments — read / reply / hide / delete comments
• instagram_manage_insights — read account & post insights
• pages_show_list, pages_read_engagement — find the Page and derive the connected IG account

Quick path — short-lived token (testing, ~1–2 hours)

1. Open the Graph API Explorer → select your app.
2. User or Page → Get User Access Token → tick the permissions above → Generate Access Token → authorize, selecting the Page your Instagram account is linked to.
3. Paste the resulting token into Access token. Instagram calls work with this token directly — no extra exchange needed.

Durable token (production)

Same chain as Facebook: exchange the short-lived user token for a long-lived one (effectively non-expiring), using your App ID and App Secret:

GET https://graph.facebook.com/v25.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_USER_TOKEN}

Finding the Instagram account ID

You usually don't need to enter it:

• Set Page ID and leave the account ID blank — the tool derives it from the Page's connected Instagram account.
• Or have the bot call the list_accounts action, which returns each Page and its connected Instagram account id + username.
• Or read it manually: GET /me/accounts?fields=instagram_business_account{id,username}.

Single-account vs multi-account mode

• Single-account — set the account ID (or the Page ID to derive it). The bot is locked to that one account.
• Multi-account — leave both blank. The bot supplies the account per action (and can list_accounts to discover them). One token can manage several Instagram accounts, e.g. one per connected Page.

You can also create multiple separate configurations (one per account) — just give each a distinct name.

Token expiry & refresh

As with Facebook, tokens can expire or be invalidated — a password change, a security event, or the ~1–2 hour life of an Explorer token. On failure the API returns a clear "session expired" / "invalid access token" error. For production, use a long-lived token. There's no automatic refresh yet — if a token dies, edit the config and paste a new one (leaving it blank on edit keeps the stored token).

Behavior to expect

• One-call publish — the tool runs the container→publish flow and waits for processing internally; the agent doesn't manage container ids.
• Daily limit — roughly 100 posts per 24 hours per account (a carousel counts as one). The bot can check remaining quota.
• Media requirements — images must be public JPEGs with an Instagram-valid aspect ratio (about 4:5 portrait to 1.91:1 landscape for feed); reels need a public video URL. Instagram fetches the media from the URL, so it must stay reachable for ~30s.
• Captions aren't clickable — for links, use "link in bio" rather than pasting a URL.
• Comments & deletion — hiding comments works, and deleting your own media works (image / reel / carousel / story).
• Insights metrics — metric names change over time (Meta deprecated several in Jan 2025). The tool passes names through as-is — check Meta's current Instagram metrics reference.

Common errors

• "…has no connected Instagram Business account" → the Page isn't linked to an IG Business/Creator account; connect one in Meta Business Suite.
• Instagram permission errors → the token is missing instagram_content_publish (or the others); regenerate it with all four instagram_* scopes.
• "session expired / invalid access token" → the token died; paste a fresh one.

Safety in autonomous runs

Like any tool, the Instagram tool carries a safety classification (mutating / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Classify the configuration to match what its token can actually do, and prefer the tighter control — scope the token to the accounts and permissions it needs. Interactive chat is never gated by these flags.

Security

The access token is stored AES-encrypted at rest and is never returned by the API — the console shows only whether a token is set. Editing a configuration without retyping the token preserves the stored one.