Why this matters

Meta exposes two completely different ways to authenticate, and they share enough vocabulary that you can build the wrong one without noticing — then tear it down when you add a second account.

• Instagram Login — host graph.instagram.com, per-account tokens you refresh every ~60 days. Built for a single account logging into your app.
• Facebook Login / Business — host graph.facebook.com, a System User token issued from a Business Manager that owns the accounts. One token reaches every account in the portfolio, and it doesn’t expire.

If you’re publishing to multiple owned accounts on a schedule, you want the second one. Pick it first and skip the rework.

There’s a bonus hiding in the Business path: the publish permission instagram_content_publish normally needs Advanced Access (Meta’s App Review queue — weeks). For accounts your Business Manager owns or is role-connected to, Standard Access is automatic. No review. That single fact is what makes this viable on day one.

The structure

These first steps claim assets and prove ownership, so Meta gates them behind your own login — you genuinely cannot script them. In business.facebook.com → your Business → Business settings → Accounts → Instagram accounts:

1. Add each Instagram account. Log into each when prompted — that’s the ownership check. If an account only shows under a Facebook Page, use the Page’s Connect Instagram.
2. Confirm each is a Business account (Instagram app → Settings → Account type). Creator will not publish via the API.
3. Link each Instagram account to its Facebook Page — you need this to resolve the numeric account ID later.

Your turn

Claim every account you intend to publish to, and switch any Creator accounts to Business now. Doing this up front avoids a confusing mid-build rejection where the API simply refuses to publish with no obvious reason.

Why this matters

The System User token is the whole point of the Business path: one non-expiring credential that reaches every account you own. You generate it once.

The structure

1. Create the app. developers.facebook.com → Create App → Instagram product, attached to your business portfolio. (Abandon any half-built Instagram-Login app — wrong model.)
2. Create a System User. Business settings → Users → System users → Add. Give it the Admin role.
3. Assign assets to the System User: the app, all the Instagram accounts, and their Pages, each at Full control.
4. Generate the token for that System User with the scopes below, choosing no expiration. Copy it once — you won’t see it again.

instagram_basic
instagram_content_publish
pages_show_list
pages_read_engagement
business_management

Your turn

Generate the token, then store it in a secret manager — never in the repo. A Worker secret, 1Password, Doppler, Vault; any of them. Everything downstream reads it from an environment variable:

export IG_ACCESS_TOKEN="<your-system-user-token>"

curl -s "https://graph.facebook.com/v25.0/me/accounts\
?fields=name,id,instagram_business_account{id,username}\
&access_token=$IG_ACCESS_TOKEN" | jq

Why this matters

The publish endpoints address each account by a numeric ig_user_id, not its handle. You’ll pass that ID on every call, so map your own slugs to the IDs once and keep them somewhere your code reads.

Your turn

Take each instagram_business_account.id from the Checkpoint call above and drop it into a small registry keyed by a slug you choose:

{
  "brand":  { "handle": "your.brand",  "ig_user_id": "<ig-user-id>" },
  "studio": { "handle": "your.studio", "ig_user_id": "<ig-user-id>" }
}

Why this matters

Publishing a reel is three calls: build a container, wait for the video to transcode, publish the container. The video_url has to be a publicly reachable URL — Meta’s servers fetch it, so local file paths don’t work. Upload to your bucket first and pass that URL.

The structure

const GRAPH = 'https://graph.facebook.com/v25.0'

async function api(token, path, params, method = 'POST') {
  const body = new URLSearchParams({ ...params, access_token: token })
  const url = `${GRAPH}/${path}`
  const res = method === 'GET'
    ? await fetch(`${url}?${body}`)
    : await fetch(url, { method, body })
  const json = await res.json()
  if (!res.ok || json.error) throw new Error(json.error?.message || JSON.stringify(json))
  return json
}

// 1. Build the container. Returns a creation_id.
async function buildReel(token, igUserId, { videoUrl, caption }) {
  const { id } = await api(token, `${igUserId}/media`, {
    media_type: 'REELS', video_url: videoUrl, caption, share_to_feed: 'true',
  })
  return id
}

// 2. Poll until the video finishes transcoding (images skip this step).
async function pollStatus(token, containerId, maxMs = 75000) {
  const deadline = Date.now() + maxMs
  while (Date.now() < deadline) {
    const { status_code } = await api(token, containerId, { fields: 'status_code' }, 'GET')
    if (status_code === 'FINISHED') return 'FINISHED'
    if (status_code === 'ERROR' || status_code === 'EXPIRED') throw new Error(`container ${status_code}`)
    await new Promise((r) => setTimeout(r, 5000))
  }
  return 'IN_PROGRESS' // still transcoding — resume later with the SAME container id
}

To tag another account or send a co-author (Collab) invite, add them to the container call. Tagging is documented; collaborators is community-confirmed but absent from Meta’s main publishing doc — so treat a rejection as a real, surfaced error, not something to swallow:

const extras = {
  user_tags: JSON.stringify([{ username: 'your.studio' }]),
  collaborators: JSON.stringify(['your.studio']),
}

Your turn

Wire buildReel → pollStatus → media_publish against one account and one hosted video. Publish a single test reel before you automate anything.

Why this matters

This is the one that caused real damage in production, and the most transferable lesson in the tutorial.

The publish call — POST /{ig}/media_publish — sometimes returns “An unexpected error occurred” even though the post went live. If you treat that error as “failed” and re-run, a naive retry builds a new container and publishes the same video again. I shipped exactly that and watched one reel post three times.

The structure

Two rules fix it.

Persist the container id before you publish, and retry the same one. Re-publishing an identical creation_id is idempotent — Meta won’t create a duplicate. So a retry either returns the real media id (it had actually published) or completes the publish that genuinely hadn’t happened. It never doubles.

// Re-publishing the SAME creation_id never duplicates.
async function publishWithRetry(token, igUserId, creationId, tries = 4) {
  let lastErr
  for (let i = 0; i < tries; i++) {
    try {
      const { id } = await api(token, `${igUserId}/media_publish`, { creation_id: creationId })
      return id
    } catch (e) {
      lastErr = e
      // "already published" → fetch and return the existing id instead of retrying
      if (/already.*publish|has already been/i.test(String(e?.message || e))) {
        try { const r = await api(token, creationId, { fields: 'id' }, 'GET'); return r.id }
        catch { return null }
      }
      await new Promise((r) => setTimeout(r, 8000))
    }
  }
  throw lastErr
}

Treat errors as terminal, not as “try again next run.” An item that errored stays errored until you look at it; only genuinely pending items are eligible to post. The failure that bit me was a loop that re-queued anything not marked done — so a post that succeeded-but-reported-failure got picked up and posted again on the next tick.

And mind the order around the slow step: build the container, save the container id and mark the item building, then poll and publish. On restart, an item still marked building resumes from its existing container instead of building a new one.

Your turn

Replace your direct media_publish call with publishWithRetry, persist the container id the moment you have it, and make your “what’s eligible to post” filter exclude error and building — only pending posts.