Skip to content

Threads

Implemented

Connect a Threads profile and review exact text, image or video posts with durable saved status.

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.

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. 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.