threads_publish_text
Publish text-only posts on Threads with optional attachments like links, polls, or GIFs. Auto-publish combines creation and publishing into one API call to avoid race conditions.
Instructions
Publish a text-only post on Threads. By default publishes in a single API call via auto_publish_text=true (faster and avoids the 4279009 'container not propagated' race condition). Supports optional link attachment, poll, GIF, topic tag, quote post, cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, location tagging via location_id, and text_attachment for long-form content (up to 10,000 chars with optional styling and link). Only one attachment type per post — text_attachment, poll_options, link_attachment, and gif_id+gif_provider are mutually exclusive. Set auto_publish=false to fall back to the legacy two-step create-then-publish flow.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Post text (max 500 chars) | |
| gif_id | No | GIPHY GIF ID. Must be provided together with gif_provider — providing only one returns an error. | |
| alt_text | No | Reserved — must be omitted. alt_text is only supported on image, video, and carousel posts; passing it here raises a Zod schema error. | |
| topic_tag | No | Topic tag for the post (1-50 chars, no periods or ampersands) | |
| is_spoiler | No | Mark content as spoiler | |
| location_id | No | Location ID for tagging the post. Use threads_search_locations to find IDs. Requires the threads_location_tagging permission on the access token. | |
| auto_publish | No | When true (default), combine container creation and publishing into a single API call via auto_publish_text=true — one HTTP request instead of two, and no risk of the 4279009 'container not propagated yet' race. Set to false to fall back to the legacy two-step flow (POST /threads, then POST /threads_publish). | |
| gif_provider | No | GIF provider. Only GIPHY is currently supported. Must be provided together with gif_id — providing only one returns an error. | |
| poll_options | No | Poll options (2-4 choices, each 1-25 chars). Creates a poll attachment. Cannot be combined with text_attachment, link_attachment, or gif_id+gif_provider. | |
| quote_post_id | No | ID of a post to quote | |
| reply_control | No | Who can reply to this post. One of: 'everyone' (default — anyone can reply), 'accounts_you_follow' (only profiles the author follows), 'mentioned_only' (only profiles @-mentioned in the post), 'parent_post_author_only' (only the author of the post being replied to — applies when this post is itself a reply, not a quote), or 'followers_only' (only the author's followers). See https://developers.facebook.com/docs/threads/reply-management/ for the authoritative list. | |
| link_attachment | No | URL to attach as a link preview card (max 5 links per post). Cannot be combined with text_attachment, poll_options, or gif_id+gif_provider. | |
| text_attachment | No | Long-form text attachment (max 10,000 chars). Renders as expandable 'Read more' block beneath the primary text. Cannot be combined with poll_options, link_attachment, or gif_id+gif_provider. | |
| share_to_ig_story | No | Cross-share this post to linked Instagram as a Story. 'light' = normal, 'dark' = dark mode. Requires threads_share_to_instagram permission and a linked Instagram account. The Threads post still publishes even if cross-share fails. | |
| text_attachment_link | No | URL to include inside the text attachment card. Requires text_attachment. | |
| text_attachment_styling | No | Text formatting for the text attachment. Ranges must not overlap. | |
| allowlisted_country_codes | No | ISO 3166-1 alpha-2 country codes (e.g., ['US','CA','GB']) restricting post visibility to those countries (geo-gating). Requires the account to be eligible — check `is_eligible_for_geo_gating` via `threads_get_profile`. The creator can always see their own posts regardless. Codes are normalized to uppercase and sent comma-joined (e.g., 'US,CA') as required by the API. |