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

---
title: Threads
description: Connect a Threads profile and review exact text, image or video posts with durable saved status.
section: channels
order: 60
status: implemented
mode: both
reviewed: 2026-11-19
sources: [src/lib/mcp/agent-post-publish-tools.ts, db/migrations/20261119T0400_agent_connected_account.sql, db/publishing.sql, src/lib/threads/threads.ts, src/lib/server/threads/ThreadsService.ts, src/lib/server/threads/ThreadsPublishing.ts, src/lib/server/threads/ThreadsPublicationStore.ts, src/worker/ThreadsPublicationWorker.ts, src/components/owner/threads-post-panel.tsx, src/lib/server/threads/ThreadsApi.ts, src/lib/server/threads/threads-metrics-reader.ts, src/lib/server/marketing/PostMetrics.ts, src/components/owner/post-performance-table.tsx, src/lib/server/threads/ThreadsConfig.ts, src/lib/server/threads/ThreadsPrivateDatabase.ts, src/lib/server/threads/ThreadsVault.ts, src/lib/server/threads/threads-database.ts, src/lib/server/threads/threads-callback.ts, src/app/integrations/threads/callback/route.ts, src/components/owner/threads-panel.tsx, src/components/owner/meta-connection-dialog.tsx, src/lib/server/owner/owner-handler-meta-routes.ts, scripts/bootstrap-db.ts, scripts/provision-meta-db.ts, db/meta.sql, .env.example, src/app/integrations/[product]/[kind]/route.ts, src/lib/server/lifecycle/meta-lifecycle-route.ts, src/lib/server/lifecycle/meta-signed-request.ts, src/lib/server/lifecycle/MetaLifecycleCallback.ts, src/worker/TokenRefreshWorker.ts, db/threads.sql, src/lib/server/threads/ThreadsScheduledPublication.ts, src/lib/server/marketing/PostScheduling.ts, src/worker/PostScheduleWorker.ts, src/lib/server/marketing/post-metrics-agent-tools.ts, src/lib/mcp/agent-post-metrics-tools.ts, src/lib/server/marketing/post-metric-mapping.ts]
tools: [get_onboarding_status, get_post_catalogue, publish_post, prepare_post_schedule, get_post_schedule, get_post, get_post_metrics, refresh_post_metrics]
next: [/docs/contracts/connections, /docs/channels/overview]
---

Publishing uses no credits. With plan enforcement on, a new owner approval and each container creation or publish request 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

Open **Connect** for Threads in Connections. The server checks actual app/debug/profile identity, basic access and granted publish/insights scopes. A requested scope does not enable a capability by itself. A different returned profile waits for **Use this Threads profile** while the current profile remains selected. Only the requesting owner can confirm it.

`get_onboarding_status` returns the owner Connect link and saved status. `startTool` is null; this candidate adds no Threads MCP publishing tool or agent automatic publishing. Tokens, codes, state and encrypted credentials stay outside those reads.

## Review and publish

Owner review supports one text post, one image or one video. Select the profile for the saved post and review the exact profile, caption and loaded media. **Approve and publish now** sends the post at once. To publish later, use **Schedule** (see Scheduled delivery). Multi-post Threads, replies and carousels are unavailable. Updated 2026-11-19: the owner can also approve a post with `publishMode: "automatic"`, and an agent with Publish can publish an automatic post; see Agent publishing.

The supported text limit is 500 UTF-8 bytes; emoji and some letters use more than one byte. The editor shows the byte count. A post can contain up to five distinct HTTP links. Images must be verified JPEG or PNG, no larger than 8 MB, 320–1440 pixels wide and within a 10:1 ratio. Video must pass actual MP4/MOV inspection within the provider limits and the app's 50 MiB saved-upload cap. Saved metadata alone does not approve a media file.

**Prepare Threads review** checks the current saved post and media. **Approve and publish now** saves the exact approval request before submission. If the response is unconfirmed, reload saved status or retry that same approval. Do not replace it with another request. A definite changed-content rejection permits a new review only after the original request has no saved publication operation.

Container creation, processing and final publication are separate states. Restart can resume a known container. Uncertain creation or publication cannot start a new send. Only a verified final post ID and owned native result are saved as published. A native link can be absent; the app does not invent one. Local tests do not prove native delivery.

A slow response can still save its exact container or final post ID after the worker lease ends. The saved intent must match the original claim and product. Recovery does not restore an expired approval or create another container. Expired preparation stops instead of running again without a time limit.

If Threads returned a final post ID and the server saved it, a failed verification read can be checked again. The worker reads that same ID only, with at most five attempts within 15 minutes of the saved acknowledgement and a one-minute wait after a failed read. Current basic read access must match the original owner, workspace, product and profile. This does not create or publish again. An unknown write with no saved final ID remains unknown; the app does not guess an ID from text or time.

After the attempt or time limit, the result stays unknown and the saved operation retains its acknowledged ID. Check the native profile. The worker cannot create or publish again from that state.

## Access and disconnect

Token expiry and data-access grant expiry are separate. Both must be current. Refresh needs an unexpired token at least 24 hours old and actual `threads_basic`. A public profile grant can extend through refresh. A private profile grant cannot extend through token refresh. The app uses verified debug expiry; it does not guess privacy from a username or token lifetime. An expired grant needs fresh consent.

Fresh consent for the same verified owner, workspace, product and profile can supply current read access for earlier published posts. The new credential has a new revision. An earlier queued approval cannot use it to send a post; fresh consent does not restore that approval.

**Manage** shows the current profile and its status. **Connect again** shows when the connection needs a new login or misses access. A working connection shows **Change profile** instead; the current profile keeps working until the new one is confirmed. Updated October 28, 2026. The worker refreshes a connected token that expires in 30 days or less and is at least 24 hours old. It checks about every 6 hours. It acts as the owner who connected the profile, and only while that owner is an active owner. The refresh stores current access without assuming all requested permissions were granted. If the worker cannot refresh the token for 60 days, the token expires. Updated October 14, 2026. An unconfirmed provider failure does not erase valid saved access. A verified revoked/expired grant requires connection again.

**Disconnect** stops local authority and fences late exchange/refresh results. **Cancel connection request** closes an initial or replacement request. Native posts remain on Threads; local disconnect does not revoke provider consent or prove provider-data erasure. Meta lifecycle callbacks are described in Provider callbacks below.

## Post insights

With actual `threads_manage_insights` access, Dashboard reads lifetime insights for the owned final post. Views and Likes use returned counters. Threads replies appear in **Comments / replies**, with **Replies** on the Threads detail. **Reposts** and **Quotes** stay separate extras; the app does not add them to Shares or guess an engagement total. Account/profile views do not fill a post's Views cell.

A returned zero appears as zero. Omitted metrics are unavailable; an empty insight response reports insufficient data. Views and Shares remain in development at the provider, with no promised delay. Malformed responses, permission failures and expired/revoked token or data-access grants fail the refresh and keep saved numbers. Access and saved credential revision are checked before and after each batch. Each destination group reads at most two posts at a time.

Updated 2026-11-19: agents read these numbers with `get_post_metrics` and refresh them with `refresh_post_metrics`. `refresh_post_metrics` needs `threads_manage_insights` to read the numbers. `get_post_metrics` reads saved numbers only and needs no channel permission. Without the permission, the refresh still succeeds, each Threads row gets `failure.code` `THREADS_PERMISSION_REQUIRED` and keeps its saved numbers. See [Read post performance](/docs/workflows/metrics).

Refresh failures apply to the saved destination group. After an intentional change to a different profile, older posts keep their cached values and a reconnect failure. Posts for the current profile can still save new metrics. The current profile's credential cannot read the older profile's posts.

## Operator setup

Use the Threads product's own `SHIPCONTENT_THREADS_APP_ID` and `SHIPCONTENT_THREADS_APP_SECRET`. Set `SHIPCONTENT_THREADS_API_VERSION=v1.0`. Do not substitute the parent Facebook or Instagram product secret. Current authorization uses `threads.com`; API calls use `graph.threads.com`.

The server preserves exact numeric user ID digits from code exchange and compares the exchanged, debug and profile identities. Threads debug requires the inspecting app token and user token to belong to the same app. Its documented response can omit `app_id`; a returned different app ID is rejected. Both token and data-access expiry still apply. Server diagnostics name only the failed OAuth step. They omit provider bodies, URLs, IDs, tokens, codes and error causes. A failed one-use code is never replayed.

Register exactly `https://<owner-host>/integrations/threads/callback`, using the configured owner origin. Production uses `https://app.shipcontent.com/integrations/threads/callback`. Authorization and code exchange use that same fixed URI. Set `SHIPCONTENT_THREADS_CONNECTION_DATABASE_URL` and `SHIPCONTENT_THREADS_WORKER_DATABASE_URL` with separate NOINHERIT logins that have only `shipcontent_threads_connection` and `shipcontent_threads_worker`, respectively.

Set `SHIPCONTENT_THREADS_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_THREADS_VAULT_KEYS`, a map of base64 32-byte keys. Keep keys used by saved envelopes. The app and worker use the same Threads key ring. No credential belongs in the browser or MCP output. For token refresh, the worker also needs `SHIPCONTENT_THREADS_CONNECTION_DATABASE_URL`, `SHIPCONTENT_THREADS_APP_ID`, `SHIPCONTENT_THREADS_APP_SECRET` and `SHIPCONTENT_MCP_AUDIENCE`.

Fresh bootstrap needs `SHIPCONTENT_BOOTSTRAP_THREADS_CONNECTION_PASSWORD` and `SHIPCONTENT_BOOTSTRAP_THREADS_WORKER_PASSWORD`, both Facebook 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 data, apply `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. Rejected provisioning changes no password. Keep operator values on the server; do not reset saved data.

Local tests do not prove a live grant, native post, deployed result or provider review approval.

## Provider callbacks

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

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

ShipContent checks the signature with the Threads app secret only. No other product secret can replace it. Meta documents this signed request for Facebook. A live Threads delivery on 2026-10-13 confirmed that the Threads callbacks use the same format, signed with the Threads app secret. 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 Threads profile 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 Threads 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 Threads profile 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 Threads profile 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-13: removing the app in Threads settings makes Meta send both a deauthorize and a data-deletion request. ShipContent then erases the provider data for that account. Owner content stays.

Set `SHIPCONTENT_THREADS_APP_ID`, `SHIPCONTENT_THREADS_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.

## Scheduled delivery

Updated 2026-10-16. The owner can schedule a Threads text post, one image or one video in the [post editor](/docs/workflows/post-draft#automatic-schedules). The owner confirms the exact profile, 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: "threads"` 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 profile of the workspace. The agent does not select a profile. Supported posts are one text post, one image or one video.

`DESTINATION_REQUIRED` means that no profile is connected, or that the post names another profile. `DESTINATION_UNAVAILABLE` means that the connected profile cannot publish now; the owner connects Threads again. Before this date, no agent call could publish or schedule on Threads.

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 Threads has not published stops.

A Threads review lasts 10 minutes, so a schedule does not use one. The saved schedule is the review. At the due time the worker checks the owner, the profile connection, the saved text and the digest of the saved media. It then creates the same publication job as **Approve and publish now**, with a new 10-minute permit. The username, scopes, token dates and credential revision can refresh in between. The profile, app, 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 Threads posts are always available for a configured connection. No flag controls them. A missing server configuration returns `THREADS_NOT_CONFIGURED`. It needs the operator. It does not ask you to connect again. No live delivery is recorded for this feature. See [scheduling errors](/docs/contracts/errors#scheduling-errors).
