Meta / Instagram integration
This covers getting Instagram content into Autumn's projects: feeds, posts, shared posts and DMs. Autumn builds for real end users, not just herself.
When to Use
Use when someone wants Instagram feed or post access, username lookups, a bot that receives shared posts, reading Instagram DMs, Meta webhooks, or work on the SecondBloom Meta app.
Standing rules
- Design for ordinary users first. Before proposing a setup, ask whether a normal user with a personal Instagram account could use it with zero setup. Routes that need the user to switch to a Creator account, link a Facebook Page, or click through the developer dashboard and Graph Explorer are dev-only. Autumn rejects those as too complicated and not serving normal users, so lead with the user-facing option and only mention the dev-only route as an aside.
- Check docs before claiming anything. Meta's Instagram APIs change often, with deprecations and new attachment types. Verify with the Meta devtools MCP
devtools_discovery(search_docs) or withweb_extracton developers.facebook.com, and cite the doc URL in the answer. - Credentials: never take access tokens or OAuth codes in chat. The user saves tokens into
$HERMES_HOME/.envthemselves.
Procedure
Clarify what "feed" means with a single clarify call. There are three cases: (a) the home feed of accounts they follow, (b) their own posts and comments, (c) content users send in. Each has a different answer; see
references/access-routes.md.Inventory the Meta side with the devtools MCP (
mcp_meta_social_technologies_*).devtools_app_listshows apps the user granted; Autumn has one app, SecondBloom, where she is admin. The MCP can read app settings, check app review and compliance, manage and test webhooks, and search the docs. Products, use cases and access tokens still need the user in the dashboard.Recommend the route from the decision table. For products, the default is the DM-share bot: users share a post or reel to the business account, which only needs to be professional, and a messaging webhook delivers it.
App Review gates outsiders. Accounts with a role on the app (admins and testers) work without App Review. Start App Review for
instagram_business_manage_messages(orinstagram_manage_messageson the Facebook Login variant) well before any non-tester traffic is needed, because it can take days.Receiver infrastructure already exists.
https://www.codepilots.co.uk/ig/webhookgoes through nginx to theigwebhookcontainer in ~/secure-webserver (see the README section there; the nginx side of the build is in thedocker-webserver-deployskill).- The verify token and app secret are in
~/secure-webserver/igwebhook/secrets.env(mode 600). - Raw events go to
igwebhook/data/events.jsonl, flattened shares toshares.jsonl. - Public pages:
/secondbloom/{privacy,terms,data-deletion}.html. - Read API (28 Oct 2026), LOCAL ONLY:
GET /ig/shares?since=&limit=,GET /ig/media/<id>andDELETE /ig/media/<id>(call only after the image is safely collected — the bot then deletes its copy) athttp://127.0.0.1:8903— no nginx route, not public, never add one. Auth:Authorizationheader, bearer scheme, valueIG_API_TOKEN(inigwebhook/secrets.env; meta-styles copy isig-bot-tokenin its.env/secrets). Direct photos are recorded withimg_…ids and media is downloaded on receipt by app.py itself. Check withpython3 ~/secure-webserver/igwebhook/smoke_api.py http://127.0.0.1:8903— never curl with the token on the command line. Tests:cd ~/secure-webserver/igwebhook && python3 -m unittest test_app(40). - SecondBloom is app_id 29264663606459560, live. The receiving IG ID is 17841417613087488.
- Anything that reads the bot's data for another app (a read API, an export) is local-only: publish it from the container on
127.0.0.1:<port>and give it NO nginx route — nginx on 8443 is reachable from Cloudflare and the tailnet. Autumn wants bot data visible only on this machine. Recipe:docker-webserver-deploy→ "Local-only API on a sidecar". - Collected media must not linger on the bot. Autumn wants the bot to delete its copy of an image once the consuming app has collected it. Implement that as an explicit acknowledgement (
DELETE /ig/media/<id>sent by the client after it has stored/used the bytes), never delete-on-GET: a successful GET doesn't prove the page kept the image, and by then the signed CDN URL has expired, so an early delete loses it for good. Smoke-test the delete path on a sentinel file the test creates itself, never on real media. - The bot is prior work relative to meta-styles (hackathon). Extending it is allowed as maintenance of that project, but its code stays out of the meta-styles repo and is never shown as hackathon-built; see
meta-hackathon-compliance.
- The verify token and app secret are in
Connect an Instagram account to the webhook in this order. Each step is a user click unless marked. It's the order that worked end to end; walk it one step at a time.
- Make the receiving IG account professional (Business or Creator).
- Turn on IG Settings → Messages and story replies → Message controls → Connected tools → "Allow access to messages". Without it, no events arrive.
- Dashboard: add the "Manage messaging & content on Instagram" use case (Instagram login, no Facebook Page needed). Then "API setup with Instagram login" → Generate access tokens → Add account. The user saves the token as
IG_ACCESS_TOKENin$HERMES_HOME/.env. - The user puts the Instagram app secret in the receiver's secrets.env. Agent: recreate the container (
docker compose up -d --no-build --force-recreate igwebhook, in the background). Confirm the secret loaded withdocker exec igwebhook python -c "import os;print(bool(os.environ.get('IG_APP_SECRET')))", which doesn't print the secret. - Dashboard webhook config: the callback URL, plus the verify token read from secrets.env. Tell the user the exact
grep IG_VERIFY_TOKEN …command in the same message that introduces the token. - Turn on the per-account Webhook subscription toggle under API setup. A saved callback URL alone delivers nothing.
- Publish the app. It needs privacy policy, terms and data deletion URLs. Meta only delivers webhooks to published apps.
- Ground truth: the user DMs the account from another account. Agent: check
docker logs igwebhookand the nginx access log for aPOST /ig/webhookfromfacebookexternalua. Don't rely ondevtools_webhook_list list_subscriptions: it showed nothing while Instagram-login webhooks were in fact delivering.devtools_webhook_testneeds the user to approve a prompt in the client.
Process media as soon as it arrives. Download each attachment
urlstraight away intoigwebhook/data/media/<media_id>, because the signed links are temporary. Check what the receiver does before relying on it: the originalapp.pyneither downloads media (files indata/media/were saved by an agent by hand) nor records direct photos (SHARE_TYPESlacks"image", so they reachevents.jsonlbut nevershares.jsonl). GrepSHARE_TYPESanddownload_mediainapp.pyfirst; if absent, either fix the receiver or fetch media yourself immediately. (Fixed 28 Oct 2026:app.pynow recordsimageattachments and downloads every attachment on receipt; once the meta-styles client collects an image viaDELETE /ig/media/<id>the file is gone, so analyse before acknowledging.) Image analysis (outfit description) runs on the local file withvision_analyze. For outfits, give the pieces as base / layer / accessory, the colour links between pieces (which colours repeat across which pieces), and a list of style keywords. That's the record downstream matching uses; see the boutique/outfit rules in memory. Note when only part of the outfit is visible, and never identify the person.
Pitfalls
- Verify-token mismatch: if the dashboard says "callback URL or verify token couldn't be validated", nginx shows Meta's GET returned 403. The user typed their own token instead of the one in secrets.env. Diagnose by comparing the logged token length with the expected length (redact the token in any output), then give the user the grep command.
- Webhook POSTs rejected after the secret is added: the container still has its old environment, because env_file is only read when the container is created. Force-recreate it.
- Send replies from a script that reads the token from
.env, never with the token on a curl command line where it shows in process listings and the transcript. Useurllib: POSThttps://graph.instagram.com/v26.0/me/messageswith the Bearer header and body{"recipient":{"id":IGSID},"message":{"text":...}}; it returns{recipient_id, message_id}. Replies are only allowed within 24 hours of the user's last message, and each reply comes back to the webhook as anis_echoevent, which must be skipped. - Real payloads, verified 14 Oct 2026 on SecondBloom.
- A shared post arrives as one attachment:
{"type":"ig_post","payload":{"ig_post_media_id","title","url"}}.titleis the caption andurlis the image onlookaside.fbsbx.com/ig_messaging_cdn/(signed). - There is no legacy
shareattachment any more. - The payload has no author username or permalink.
- A photo sent directly arrives as
{"type":"image","payload":{"url"}}. The file can be a PNG even though it's served as image/jpeg. - Both signed URLs downloaded fine without a token at once. Save media on arrival rather than relying on the URL later.
- Our own sent messages come back as echoes with
is_echo: true.
- A shared post arrives as one attachment:
- Pass
max_results≤3 todevtools_discoverysearches. Results include whole page boilerplate, and 5 results can be about 80KB and spill to disk. - Meta's doc samples write
&fields=straight after the node ID. As the first parameter it has to be?fields=, or the request fails. - An Instagram login through a Facebook OAuth redirect appends
#_=_. Strip URL fragments before parsing any pasted redirect.
Meta Model API (Muse / SAM). This is not the Graph API.
- Key and endpoint: use
MODEL_API_KEYfrom$HERMES_HOME/.env;MUSE_API_KEYis also set. The base URL ishttps://api.meta.ai/v1and the API is OpenAI-compatible.GET /v1/modelson this key listsmuse-image-1.0,sam-3.1,muse-spark-1.1..1.3,muse-wonder-1.0andmuse-voice-transcribe-1.0. - Muse Image: call
POST /v1/images/generationsor/v1/images/editsfor one-off images; use the Responses API for editing over several turns. It costs $0.01 per image. - SAM 3.1: call
POST /v1/responseswith modelsam-3.1. The input is a short noun phrase (input_text) plusinput_image, andstream:trueis required. The output is special-token text containing boxes and masks; see dev.meta.ai/docs/sam/reading-segmentation. Send one object type per request. It costs $2.50 per 1,000 images. - Quota (verified 14 Oct 2026): the key is on a subscription with a rolling usage window. When the quota is used up, Spark returns 429 with "Subscription quota exhausted… resets at " and a
resets_atfield. SAM returns 429 with only "Service temporarily unavailable" for the same cause. Probe with a tiny Spark call to read the reset time, and don't retry in a loop. Hermes' own chat on the meta-ai provider uses the same quota.
References
references/access-routes.md: decision table (home feed, own media, username lookup, DM share, extension), and the Messaging webhook and Conversations API endpoints and limits.