Skip to content

Facebook Pages

Implemented

Connect Facebook, select one authorized Page, and manage its saved access.

Publishing uses no credits. With plan enforcement on, a new owner approval and each text, photo, video start or final video submission require publishing access. Unsent work stops if that access ends. An accepted provider result can still be saved and verified. Exact saved approval replays remain available. Updated October 16, 2026.

Connect and select a Page#

Open Connect for Facebook Page in the workspace's Connections page. Sign in to Facebook, grant access, then select one returned Page. The selection shows the granting Facebook login name and the Page name/ID. A callback does not select a Page automatically. Replacing a connection requires the owner's explicit selection of the proposed Page.

If Page selection is already pending, reload Connections to continue the same saved request. The other channel tiles remain available during that review.

The server checks the actual app, user identity, granted permissions and current Page tasks. The Page must have CREATE_CONTENT and actual pages_show_list, pages_read_engagement and pages_manage_posts access. ANALYZE plus read_insights enables feed insights. This analytics permission is optional: denial keeps ordinary Page text/photo publishing available. The server checks current grants and tasks again before a read. Requested permissions are not proof of a grant. public_profile supplies the validated login identity displayed during selection.

If the Page belongs to a business portfolio, Meta can return an empty Page list until business_management is granted. The October 12, 2026 ShipContent test confirmed this: the existing Page grants and full Page control returned no Pages; adding business_management returned the selected Page. pages_manage_metadata alone did not fix discovery and was removed. Business access permits portfolio asset management and access delegation. Approve that access explicitly and select only the required current Page and portfolio. ShipContent uses it for Page discovery and has no portfolio-management action.

Facebook and Threads have no MCP start or publishing tool in this candidate. get_onboarding_status gives the signed-in owner Connect link and saved state; startTool is null. A saved connection does not prove current provider access, delivery or customer eligibility.

Manage access#

Manage opens Page selection or the current connection. Expired User access needs a new Facebook login. ShipContent does not use a saved Page token alone: each publish, schedule and metrics read also needs current User access. See Access lifetime and refresh.

Connect again shows when the connection needs a new login or misses publish or feed insights access. A working connection shows Change Page instead. The dialog does not list each permission. Updated October 28, 2026. Denial or a failed new Page choice keeps the working connection and credential until a verified replacement is selected. A verified replacement changes the credential revision; an older publication approval cannot use that new credential. An automatic refresh of the same User, Page, tasks and permissions keeps the revision.

Disconnect removes local authority and stops pending connection results from restoring it. It does not delete native posts or revoke Facebook consent. A provider request already in flight can still finish. This local disconnect does not start provider deauthorization or provider-data erasure. Those use the callbacks in Provider callbacks below.

Access lifetime and refresh#

Updated 2026-11-19. Each connection has one saved end date for its User access. It is the earliest of the token expiry and the data access expiry that Facebook reports for the token. When Facebook reports no expiry, the date is 60 days after the check. Publish, schedule and metrics calls fail with FACEBOOK_RECONNECT_REQUIRED when this date has passed.

Facebook documents two separate limits. A long-lived User token lasts about 60 days. Data access lasts 90 days, based on when the person was last active, and the person must authorize the app again to regain it (Meta: long-lived tokens, Meta: authentication versus data access). Meta does not document that a new exchange of a long-lived token extends it, so ShipContent saves the date that debug_token reports after each exchange.

Automatic refresh. The worker checks every 6 hours. It refreshes each connected Facebook connection whose access ends in 30 days or less and that no connect or refresh confirmed in the last 24 hours. It acts as the owner who connected the Page, and only while that owner is an active owner with account access. For each connection it does these steps:

  1. It exchanges the saved long-lived User token for a new one (grant_type=fb_exchange_token).
  2. It checks that the new token is for the same Facebook user and app, and that the required permissions are granted.
  3. It reads the Page and its tasks again. The Page must still have CREATE_CONTENT.
  4. It saves the new token and the new end date.

The new end date never goes past the data access date that Facebook reports. ShipContent does not assume that a new token extends data access. When data access ends, the owner must connect again.

A refresh does not change the selected Page. The credential revision stays the same when the Facebook user, the Page, the tasks and the permissions are the same, so an approved or queued publication stays valid. A change in tasks or permissions gives a new revision, and an older approval cannot use it. A refresh also reads the Page name again. If the Page was renamed, an approved publication that was not sent yet stops with CONTENT_CHANGED, because the approval names the Page. Approve it again.

A failed refresh. The saved access stays as it was, and the next sweep tries again, in these cases: Facebook does not answer or answers with an error (an outage or a timeout), the new token is for another Facebook user, or the Page is no longer returned. If Facebook refuses the exchange, the worker also checks the saved User access once. If that check passes, the connection stays connected. If that check fails, the worker marks the connection reconnect-required and removes the saved credential. A refresh saves its result only when the saved credential is still the one that it read. A refresh that lost a race with a newer refresh changes nothing. A Page that Facebook no longer returns stops publication at the next publish check.

When the owner must connect again.

  • The saved end date has passed, because the token expired or data access ended.
  • Facebook no longer accepts the saved User access, for example after the person removed the app or revoked a permission.
  • The Page lost CREATE_CONTENT, or a required permission is no longer granted.

An expired or missing credential shows as reconnect-required on the Connections tile, in get_onboarding_status channels[].state and in socialConnections[].status. Use Connect again. A working connection shows its end date in socialConnections[].expiresAt. Before 2026-11-19 these reads showed connected after the date had passed.

Owner publication#

Select the saved Facebook Page for the draft. Review text, one JPEG/PNG photo, or one Page Reel and select Approve and publish. Approve and publish requires review mode and no planned time. To publish later, use Schedule (see Scheduled delivery). Other Facebook formats are unavailable. Updated 2026-11-19: Approve and publish also accepts a post with publishMode: "automatic". An agent with Publish can publish an automatic post; see Agent publishing.

The review shows the Page name/ID, granting login, public visibility, caption and current media. Media approval waits for the current preview to load. A failed preview has Reload preview. Photos are below 10 MB. Reels require 3–90 seconds, 9:16, at least 540×960 and 24–60 fps. The app upload cap is 50 MiB; the current Page Reel limit is 30 per moving 24 hours.

Preparation and the worker inspect actual saved bytes and bind their hashes to the exact post and Page. Create/upload/finish requests have durable intents before provider calls. The worker checks current account access, Page tasks and the original owner/revision again before each send. Expired account access stops further sends. An acknowledgement from a request already in flight is still saved. Unknown results never cause another publication request. Reload reads the saved operation by post and retains the original approval request. A provider upload ID is not a published post.

When account access ends, verification of an acknowledged result also waits for current access. The saved acknowledgement remains available for later recovery.

Only native verification saves the final post ID and delivery status. Reel verification requires publishing_phase.status: "complete", publishing_phase.publish_status: "published", and membership in the selected Page's Reel list. A ready upload alone does not confirm publication. Text/photo links use an actual returned permalink. A confirmed Reel uses the permalink_url that Graph returns for the video, resolved against https://www.facebook.com. A missing or invalid value does not fail verification: the Reel has no link. The app does not construct one from its ID. Reels confirmed before 2026-10-17 keep no link.

Dashboard insights#

The dashboard uses per-post lifetime post_media_view for supported feed text/photo Views. Likes comes from the documented Likes edge; a reaction total that includes Care is not Likes. Facebook's comment summary counts people who commented, so the app shows that count as a separate extra and leaves common Comments unavailable. Shares uses the returned post share count. Missing data stays unavailable; a returned zero stays zero. Failed, denied or malformed reads preserve the last successful snapshot.

Updated 2026-11-19: agents read these numbers with get_post_metrics and refresh them with refresh_post_metrics. Feed views and facebookReach need read_insights, pages_read_engagement and the Page task ANALYZE; without them each value is needs-permission. A video post fails with FACEBOOK_REEL_INSIGHTS_PERMISSION_REQUIRED and keeps its earlier numbers. See Read post performance.

After selecting a different Page, older Page posts keep their cached values and a reconnect failure. The current Page's posts can still save new metrics. The current Page credential cannot read the older Page's posts.

Page/account totals never fill a post row. A returned zero stays zero. Missing metrics use not-returned; empty lifetime data uses insufficient-data. Provider denial, revoked access and failed reads keep the previous cache. Some feed Page insights need at least 100 Page likes and can take about 24 hours to update.

Operator setup#

Use a Facebook Login for Business User-token configuration. Set SHIPCONTENT_FACEBOOK_APP_ID, SHIPCONTENT_FACEBOOK_APP_SECRET, SHIPCONTENT_FACEBOOK_LOGIN_CONFIG_ID and SHIPCONTENT_FACEBOOK_GRAPH_VERSION=v26.0. Use the parent Facebook app credentials, with no Instagram/Threads secret fallback. The configuration controls requested permissions; the URL uses config_id.

In that configuration, request pages_show_list, pages_read_engagement and pages_manage_posts for connection and publishing. public_profile is granted automatically. Add optional read_insights for feed insights. Add business_management when portfolio Page discovery requires it, with the owner's explicit consent. The October 28 ShipContent configuration has these five selected permissions and excludes pages_manage_metadata. A saved config_id does not prove these settings or user consent. Keep the app identity and callback unchanged unless the actual provider configuration requires a change. Advertising permissions are not needed.

Register exactly https://<owner-host>/integrations/facebook/callback. Set separate SHIPCONTENT_FACEBOOK_CONNECTION_DATABASE_URL and SHIPCONTENT_FACEBOOK_WORKER_DATABASE_URL. Their NOINHERIT logins have only shipcontent_facebook_connection_admin and shipcontent_facebook_worker, respectively. Never use the app, admin or a shared provider credential URL for either role.

Callback host validation reviewed 2026-10-11: the callback uses the configured public owner host when the app runs behind a proxy. An internal 0.0.0.0 bind URL is allowed only with the matching public Host. X-Forwarded-Host cannot replace it.

Set SHIPCONTENT_FACEBOOK_VAULT_ACTIVE_KEY_ID and SHIPCONTENT_FACEBOOK_VAULT_KEYS. The key map contains base64 32-byte keys. Keep older keys while stored envelopes use them. The app and worker use the same Facebook key ring. No token or key belongs in browser code or MCP output.

For automatic refresh, the worker also needs SHIPCONTENT_FACEBOOK_CONNECTION_DATABASE_URL, SHIPCONTENT_FACEBOOK_APP_ID, SHIPCONTENT_FACEBOOK_APP_SECRET, SHIPCONTENT_FACEBOOK_LOGIN_CONFIG_ID and SHIPCONTENT_MCP_AUDIENCE, with the vault keys above. Publication needs only the worker login. Without the connection login, the worker logs token_refresh_provider_unconfigured at start and never refreshes Facebook access.

Fresh bootstrap uses SHIPCONTENT_BOOTSTRAP_FACEBOOK_CONNECTION_PASSWORD and SHIPCONTENT_BOOTSTRAP_FACEBOOK_WORKER_PASSWORD, the two Threads passwords, and SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_PASSWORD / SHIPCONTENT_BOOTSTRAP_META_LIFECYCLE_WORKER_PASSWORD, plus SHIPCONTENT_BOOTSTRAP_META_STATUS_PASSWORD for the app-only read-only status role. For saved databases, apply the forward migrations with pnpm db:migrate, then run node --import tsx --conditions=react-server scripts/provision-meta-db.ts with the bootstrap database URL and all seven password variables. It refuses unsafe existing roles and rolls back a rejected setup. Do not reset a saved database. Operator values stay on the server.

Local implementation, provider configuration, deployed behavior and actual native acceptance are separate checks. October 12 test-role consent and Page publication do not establish customer eligibility or provider review approval. Standard-access permissions only work for people with an app role until Meta grants the required advanced access.

Scheduled delivery#

Updated 2026-10-16. The owner can schedule a Facebook text post, one JPEG/PNG photo or one Page Reel in the post editor. The owner confirms the exact Page, text and media. A planned date alone never publishes.

Agent publishing#

Added 2026-11-19. The owner can give an agent Publish in Agents; read list_workspaces.access.canPublish. For a post with channel: "facebook" and publishMode: "automatic", the agent calls publish_post to publish now, or prepare_post_schedule to publish at a later time. Both use the one connected Page of the workspace. The agent does not select a Page. Supported posts are text, one JPEG/PNG photo and one Page Reel.

DESTINATION_REQUIRED means that no Page is connected, or that the post names another Page. DESTINATION_UNAVAILABLE means that the connected Page cannot publish now; the owner connects Facebook again. Before this date, an agent call for a post with no selected Page returned FACEBOOK_RECONNECT_REQUIRED, and no agent call could publish or schedule on Facebook.

Read get_post for post.delivery, and get_post_schedule for a blocker code. If the owner disconnects the agent, its pending schedules are cancelled and a job that has sent nothing stops.

At the due time the worker checks the owner, the Page connection and tasks, the saved text, and the digest of the saved media. It then creates the same publication job as Approve and publish. The Page name, login name, scopes, tasks and credential revision can refresh in between. The Page, app, granting Facebook user, text and media must not change. If a check fails, the schedule is blocked and nothing is sent. The 15-minute window limits the start. An uncertain provider step is never sent again.

Scheduled Facebook posts are always available for a configured connection. No flag controls them. A missing server configuration returns FACEBOOK_NOT_CONFIGURED. It needs the operator. It does not ask for a new login. No live delivery is recorded for this feature. See scheduling errors.

Provider callbacks#

Updated 2026-10-12. Register two URLs in the Facebook app settings, on the owner host. Meta sends a signed POST to each URL.

  • Deauthorize callback: https://<owner-host>/integrations/facebook/deauthorize
  • Data deletion request URL: https://<owner-host>/integrations/facebook/data-deletion

ShipContent checks the signature with the Facebook app secret only. No other product secret can replace it. A request with a wrong signature, product or format gets 400 INVALID_SIGNED_REQUEST and changes nothing. Missing app settings give 503 LIFECYCLE_NOT_CONFIGURED. A storage fault gives 503 LIFECYCLE_UNAVAILABLE, and Meta can retry. Other methods give 405.

Deauthorize removes local access for the verified Facebook user in this app. It covers every workspace and owner that saved this connection. It stops publications that have not started, and their posts show that Facebook access was removed and must be reconnected. A publication that already sent a request is not stopped. It keeps posts, metrics and history. A request already in flight can still save its result, but it cannot restore access. An older callback does not disconnect a newer connection or cancel a newer connection request. A token refresh does not make a connection newer. An unknown Facebook user gets 200. Native posts and Meta consent stay unchanged.

Data deletion returns url and confirmation_code. The URL opens the neutral status page /data-deletion/{token} on the owner host. ShipContent erases the provider copies for every owner that saved this connection. This includes a connection request that returned this Facebook user but did not finish. The page shows Completed only when all owners are done. The link expires 30 days after the last owner completes. Owner uploads, drafts and business facts stay. A repeated request returns a new link for the same work and never starts a second erasure.

Updated 2026-10-14: after data deletion, Connections hides older Facebook Connect failures. This also applies when no Page was selected or no posts were published. A new Connect attempt still shows its current status.

Updated 2026-11-04: a live test on 2026-10-13 delivered both Facebook callbacks with valid signatures. When a person removes the app in Business integrations, Meta sends the deauthorize callback only. Meta sends the data-deletion callback only when the person selects Removed → View details → Send Request. ShipContent then erases the provider data for that account. Owner content stays.

Set SHIPCONTENT_FACEBOOK_APP_ID, SHIPCONTENT_FACEBOOK_APP_SECRET, SHIPCONTENT_OWNER_ORIGIN and SHIPCONTENT_META_LIFECYCLE_DATABASE_URL. The origin builds the status URL; the request Host is never used. Live Meta delivery to these URLs was verified on 2026-10-13.