How to connect Instagram to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Instagram from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Instagram tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Instagram call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

The account is a personal one. Meta's Instagram Graph API only serves Professional accounts, so the OAuth connection completes, the agent reports success, and then every media call returns nothing. Switch to a Business or Creator account in the Instagram app under Settings, then Account type and tools, and link it to a Facebook Page if you plan to publish. Reconnect from the dashboard afterwards so the grant picks up the new account type. Worth separating from advice you will find elsewhere: the steps about creating a Meta app, requesting permissions, or submitting for App Review do not apply to this connection, but the Professional-account and linked-Page requirements do, because those are properties of your account rather than of the app.

Ask the agent to diagnose it:

Run instagram_get_user_info and tell me exactly what account type and username you are connected to. Then run instagram_get_ig_user_media and report how many items came back.

Two causes, and they are distinguishable in one call. The first is a partial approval: Meta's consent screen lets you decline individual permissions, so a connection can read your profile and media while every publish attempt fails. Reconnect from the dashboard and accept the whole set. The second is a placeholder argument: an agent that has not listed anything yet will invent an ig-user-id or media id, and the shape is valid enough to reach Meta, which answers with a permissions error rather than a not-found. That is why it looks like a scope problem when it is a bad id. Run instagram_get_user_info to get the real id, then instagram_get_ig_user_media for real media ids, and retry with those.

Ask the agent to diagnose it:

Run instagram_get_user_info and show me the exact user id. Then run instagram_get_ig_user_media and list the first five media ids. Do not retry the failed call until both have returned.

Instagram publishing is two calls, not one. The first creates a media container that holds the image or video and the caption; the second publishes it. An agent that runs instagram_post_ig_user_media and stops has done half the job, and the post exists only as an unpublished container. Ask for instagram_post_ig_user_media_publish explicitly. If the publish call itself fails, check the publishing allowance with instagram_get_ig_user_content_publishing_limit, because a full window fails at exactly this step. Videos add a wrinkle: Meta processes them asynchronously, so a container can be created and not yet be ready to publish for a short period.

Ask the agent to diagnose it:

Tell me which Instagram tools you called in order and what each returned. If you created a media container, give me its id and whether you called the publish tool afterwards.

Try reconnecting Instagram and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Instagram: link your Instagram account once in the browser and Hermes Agent can call the Instagram API through 29 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Instagram in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Instagram in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Instagram working from chat.

Yes. Building it yourself means a Meta developer app, the Instagram Graph API, permissions like instagram_basic and instagram_content_publish, and App Review before the integration works for anyone outside your test users. That review exists because Meta gates content publishing, and it is the reason most people never finish. ClawLink connects through an already-reviewed app, so the work reduces to approving access on Meta's own screen. The permissions model is unchanged: Meta still governs what the grant covers, and you can revoke it from Business Integrations in your Instagram or Facebook settings whenever you want.

Yes, and this is the one Meta requirement a hosted connection cannot remove. The Instagram Graph API only works with Professional accounts, meaning Business or Creator, and publishing requires the account to be linked to a Facebook Page. Both are settings on your side, both are free, and both take a couple of minutes in the Instagram app under Account type and tools. What ClawLink removes is the developer-app and App Review layer above that. If the agent connects successfully and then cannot see any media, a personal account is the first thing to check.

Carousels yes, through instagram_create_carousel_container followed by instagram_post_ig_user_media_publish. Stories can be read through instagram_get_ig_user_stories. Publishing on Instagram is deliberately a two-step process in Meta's API: you create a media container first and publish it second, which is why a single "post this" instruction sometimes creates a container and stops. Ask for both steps explicitly, or tell the agent to publish once you have seen what it built.

Meta enforces a publishing limit per Instagram account, and the toolset exposes it directly: instagram_get_ig_user_content_publishing_limit reports what you have used and what remains against the current window. Ask the agent to check that before a bulk run rather than after, because hitting the ceiling mid-batch leaves half the queue unpublished and produces an error that looks like a broken connection.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.