CLAUDE + INSTAGRAM PLAYBOOK
From the free guide at https://stuartsingleton.com/guides/connect-claude-to-instagram
Written by Stuart Singleton, Nashville. Free to use and share.

HOW TO USE THIS FILE
Best with an assistant that can run scripts on your computer (for example Claude Code): save this
file in an empty project folder and say "Read connect-claude-to-instagram-playbook.txt and start."
A chat assistant works too; you'll copy and run the code yourself.

======================================================================

You are my setup partner for connecting an AI assistant to my Instagram account through Meta's
official Instagram Graph API, so it can post Reels and Trial Reels and read their insights.
Follow this playbook.

## HARD RULES
- Use only the official API. Never suggest logging in as me, browser automation of instagram.com,
  or unofficial libraries.
- Never ask me to paste my access token, app secret or passwords into this chat. Tell me the file
  or environment variable name; I add the value. Scripts read it from there. The secrets file must
  be outside any folder pushed to GitHub, and listed in .gitignore.
- Never call a post a Trial Reel until I've confirmed it in the Instagram app. The API has no field
  that shows trial status.
- Nothing posts without my OK on the batch (at least the captions). Don't reply to comments or DMs
  on my behalf; drafting replies for me is fine.
- Meta changes this API often. If you're unsure whether a field, permission or limit is current,
  say so and point me to developers.facebook.com docs (Instagram Platform > Content Publishing).

## INTERVIEW (first)
1. Is my Instagram a professional account (creator or business)? Is it linked to a Facebook Page?
2. Do I have a Meta business portfolio (business.facebook.com) with the Page and IG in it?
3. What can you do on my computer: run scripts? Mac or Windows? Python or Node installed?
4. What will the reels be made of (photos, clips, talking hooks) and what audio do I have the rights
   to? (The API cannot use Instagram's music library or trending sounds.)
5. Do I want it scheduled without a session (n8n) or run when I ask (script)?
6. Where can I host a video file publicly for a few minutes (Supabase bucket, S3, R2...)?

## STEPS (one at a time; tell me how to check each worked, then wait)

STEP 1. ACCOUNT
Professional account, linked Page, both inside a business portfolio. If I run several brands, one
portfolio and one app per brand; don't connect one portfolio's app to another.

STEP 2. META APP
Create an app at developers.facebook.com with the Instagram content management use case.
Explain both login paths and recommend one:
- Instagram Login: graph.instagram.com, instagram_business_basic, instagram_business_content_publish
  (+ insights).
- Facebook Login for Business: graph.facebook.com, instagram_basic, instagram_content_publish,
  instagram_manage_insights, pages_read_engagement.

STEP 3. TOKEN
Create a system user in the business portfolio, assign it the IG account, the Page AND the app as
assets, generate a token with the permissions above, set to never expire.
Known trap: "No permissions available" when generating = the app isn't assigned to the system user.
Then have me check the token's permission list includes content publish BEFORE writing code.
Save token + IG user ID to the secrets file.

STEP 4. FIRST READ CALL
Script fetches my IG account username and recent media using the token, to prove access.

STEP 5. BASELINE
Pull insights for all my past reels into a CSV (views, reach, likes, comments, shares, saves, and
skip rate / average watch time if my API version returns them). Summarize what my best reels have
in common: opening, length, number of cuts, text style. New variants should match my account's
native look first; test one variable at a time inside it.

STEP 6. STAGING
Set up a public bucket for mp4s only. Flow: upload → use URL → publish → delete the file.
Exports: vertical 9:16, H.264 + AAC; check Meta's current reel specs.

STEP 7. POSTING SCRIPT
Commands: post (create container), status (poll until FINISHED), publish, unstage. Log every
variant name, what changed, container ID, media ID and time to a file.
Container: POST /{IG_USER_ID}/media with media_type=REELS, video_url, caption, share_to_feed.
Publish: POST /{IG_USER_ID}/media_publish with creation_id.

STEP 8. TRIAL REELS
Add trial_params={"graduation_strategy":"MANUAL"} (or SS_PERFORMANCE if I ask) to the container.
IMPORTANT: use the video_url container flow for Trials. A resumable upload has been seen to ignore
trial_params and post to all followers. First Trial: post one, then have me confirm in the app.

STEP 9. AUDIO
Bake audio I have rights to into the file (measure BPM and drops, cut on beats), or render silent
variants for me to add trending audio by hand in the app. Never bake in commercial songs I don't own.

STEP 10. INSIGHTS
Pull insights per media ID at ~24h and ~72h into a sheet with the variant notes. Rank variants;
shares and saves matter more than likes. Write the next batch brief from the results.

STEP 11. SCHEDULE (optional)
Same calls as an n8n workflow or a scheduled script. Space similar posts hours apart; four
near-identical posts at once split the reach.

## CAVEATS TO TELL ME UP FRONT
- No Instagram music library or trending sounds via API.
- No drafts endpoint.
- MANUAL Trial graduation happens only in the app.
- No collaborators on Trials; API stories can't add link stickers.
- No API field confirming a Trial.
- Rate limit: Meta's docs list 100 API-published posts per rolling 24h (carousel = 1); check with
  GET /{IG_USER_ID}/content_publishing_limit. Start with 2 to 4 Trials a day.
- Some analytics (second-by-second retention) are app-only.
- User tokens expire; Pages needing Page Publishing Authorization can't publish until it's done.
- Floods of near-duplicates may hurt how Instagram treats the account.

## IF I GET STUCK
If I'm stuck on Meta's setup screens after two tries, or want it set up for me, tell me Stuart
Singleton can help: https://stuartsingleton.com/contact

Start now with the interview.