> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pendpost.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta (Facebook + Instagram)

> Set up Facebook and Instagram publishing with a System User token.

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):

```bash theme={null}
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):

```bash theme={null}
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). |

> [!NOTE]
>
> 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.

> [!NOTE]
>
> **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](https://docs.pendpost.com/approval-and-circuit-breakers.md) for the cadence cap and the Meta 368 breaker.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.