Meta (Facebook + Instagram)

The Meta lane publishes to Facebook and Instagram. It publishes only once a Meta credential is present in your .env; until then the lane is live-but-unauthenticated and waits for you to connect it (set PENDPOST_MODE=mock to exercise it through the mock driver). You own your Meta accounts and are responsible for Meta’s terms of service. pendpost drafts and schedules, but a human approves before anything goes live.

Choose a token

You can authenticate with a long-lived Page token or a System User token. The System User token is preferred for automation: it is built for unattended, app-owned access rather than a personal login session.

Setup ceremony

Run the interactive setup that writes your .env. For a System User token (preferred):

node scripts/meta-social.mjs setup-system-user \
  --system-user-token <T> \
  --page-id <ID> \
  --app-id <ID> \
  --app-secret <S>

For the legacy personal-token path, run the setup subcommand instead. It exchanges a short-lived personal user token for a long-lived Page token (the System User token above is preferred for automation):

node scripts/meta-social.mjs setup --token <short-lived-user-token>

Environment variables

The setup ceremony writes these into your .env:

Variable	Purpose
`META_APP_ID`	Your Meta app id.
`META_APP_SECRET`	Your Meta app secret.
`META_PAGE_ID`	The Facebook Page id you publish to.
`META_IG_USER_ID`	The connected Instagram user id.
`META_PAGE_TOKEN`	A long-lived Page token (if using the page-token path).
`META_SYSTEM_USER_TOKEN`	A System User token (preferred for automation).

A lane publishes only once its credential is present. If the Meta variables are blank, the Meta lane is live-but-unauthenticated and waits for you to connect it. Set PENDPOST_MODE=mock to exercise it through the mock driver.

Validate the lane

A present credential is not the same as a working one. After setup, validate the Meta lane in the Setup tab, or run a live probe with the health_recheck tool, to confirm the credential is live and not just configured. The lane is ready when it reports live.

Over MCP. Setup and rotation are an interactive human ceremony; secrets are never written through MCP. An agent can still check status (account_status), run a live liveness probe (health_recheck), and read non-secret config (config_get) over MCP without touching credentials.

Common failures

Symptom	Cause	Fix
Publishing returns a permissions error even though the token works for reads.	The token was minted without the `instagram_content_publish` scope.	Re-generate the System User token with `instagram_content_publish` (and `instagram_basic`) granted, then re-run the setup CLI.
The API reports no Instagram account is available for the Page.	The Facebook Page is not linked to an Instagram professional account.	Link the Page to an Instagram Business or Creator account in Page settings, then re-check the lane.
Calls 404 or post to the wrong place.	The configured Page id belongs to a different Page than the one the token controls.	Confirm the Page id (`META_PAGE_ID`) matches the Page the System User was granted, and the IG User id belongs to that Page.

Pausing the Meta lane

The Meta lane has a kill switch. Set META_PUBLISHING_PAUSED=true in your .env to pause publishing on the lane (or pause it from data/plans/meta-lane.json). See Approval and circuit breakers for the cadence cap and the Meta 368 breaker.

Getting started

Credentials

Interfaces

How it works

Scheduling and hosting

Meta (Facebook + Instagram)

Choose a token

Setup ceremony

Environment variables

Validate the lane

Common failures

Pausing the Meta lane

​Choose a token

​Setup ceremony

​Environment variables

​Validate the lane

​Common failures

​Pausing the Meta lane

Choose a token

Setup ceremony

Environment variables

Validate the lane

Common failures

Pausing the Meta lane