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: connect your account with Facebook, or paste an access token, then assign the tool to a bot.
What it can do
The agent chooses an action per call. Available actions:
- Publish - image, carousel, and reel posts (supply
image_urlsand/orvideo_url), pluspublish_story. - Read - list media, get a single media, and account & post insights.
- Comments - list, add a new top-level comment (
comment_media- the link-in-first-comment pattern), reply to existing ones, hide/unhide, and delete. - Manage - delete a media, and check the publishing quota.
- Discover -
list_accountsreturns each Page and its connected Instagram account id + username.
Connect your account
Open Tools → Add tool → Instagram. There are three ways in. Whichever you choose, the account must first meet the eligibility rules below.
Connect with Facebook
The quickest. Click Continue with Facebook, sign in, and pick the Facebook Page your Instagram account is linked to. There's no token to copy. Hania finds the Instagram account from the Page, names the configuration after it, for example "Instagram (@acmebakery)", and locks it to that one account.
Pick a single Page. If you grant more than one, Hania asks you to run Connect again and grant only one. If the Page you pick has no Instagram account linked to it, Hania tells you so.
Use a connected Instagram channel
If the account is already connected as an Instagram channel under Channels, choose Use a connected Instagram channel and pick it. No new sign-in is needed. It works the other way round too: when you connect an Instagram channel, Use an existing Instagram tool connection sets the channel up from an account you connected here.
Enter the details manually
Choose Enter the details manually instead and fill in the fields below. You'll need an access token, and How to get an access token walks you through it. This is also the way to set up multi-account mode.
When the assistant sets up an agent that needs your Instagram account, it can ask for it in the chat. The card there has the same Continue with Facebook button.
Reconnecting
An account connected with Facebook or from a channel shows as Connected when you edit it, and its credentials aren't editable there. To replace them, use Reconnect and run either option again. The name and description stay as they are, and you can change the description and safety settings at any time.
An account you set up with a token can be switched over too. Edit it, choose Connect with Facebook or a channel instead, and connect. Hania replaces the stored token with the new connection.
Configuration
If you enter the details manually, 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 connect, the account has to be set up correctly:
- Make the account Business or Creator. In the Instagram app: Settings → Account type and tools → Switch to professional account.
- 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.
- Only if you enter the details manually: 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
You only need this if you enter the details manually. Connect with Facebook doesn't ask for a token.
Required permissions
instagram_basic- read the account & its mediainstagram_content_publish- publish posts / reels / storiesinstagram_manage_comments- read / reply / hide / delete commentsinstagram_manage_insights- read account & post insightspages_show_list,pages_read_engagement- find the Page and derive the connected IG account
Quick path - short-lived token (testing, ~1–2 hours)
- Open the Graph API Explorer → select your app.
- User or Page → Get User Access Token → tick the permissions above → Generate Access Token → authorize, selecting the Page your Instagram account is linked to.
- 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_accountsaction, 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_accountsto 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" or drop the link in a first comment (
comment_media) rather than pasting a URL in the caption. - Comments & deletion - hiding comments works, and deleting your own media works (image / reel / carousel / story). Comments aren't supported on live-video media.
- 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 fourinstagram_*scopes. - "session expired / invalid access token" → the token died; paste a fresh one.
Safety in autonomous runs
A new Instagram configuration starts with read-only, destructive and sends-data-externally all off. Read-only is off because the tool publishes, replies and deletes. Destructive is off because turning it on would stop every post in unattended runs unless the agent is allowed destructive actions. To have an agent wait for your sign-off before it uses the tool, set the tool's Approval to Always on that agent.
Like any tool, the Instagram tool carries a safety classification (read-only / 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.