---
name: social-media-post
description: Create, schedule, and manage social media posts using PostFast. Use when the user wants to publish, schedule, or manage posts on Facebook, Instagram, X (Twitter), TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, or Google Business Profile.
---

# Social Media Post via PostFast

You have access to PostFast MCP tools for social media scheduling and management.

## Setup Check

If any PostFast tool call fails with an authentication/401 error, tell the user:
1. Go to https://app.postfa.st/dashboard, click **API** in the sidebar, and generate a key
2. Set the `POSTFAST_API_KEY` environment variable with the key

## Posting Workflow

1. **List accounts** — Call `list_accounts` to see connected social media accounts. Each account has an `id`, `platform`, `platformUsername`, `displayName`, and a `connectionStatus` (`CONNECTED` or `DISABLED`) with an optional `disabledReason`. If `connectionStatus` is `DISABLED`, the account won't publish until the user reconnects it — warn the user and don't schedule to it.

2. **Prepare media** (if needed) — If the user has images or videos to attach:
   - Use `upload_media` with the local file path — it handles getting a signed URL, uploading, and returning a `key` and `type` (IMAGE or VIDEO)
   - Supported formats: JPEG, PNG, GIF, WebP (images), MP4, WebM, MOV (video)
   - Size limits: 10MB images, 250MB video, 60MB documents (PDF/DOC/DOCX/PPT/PPTX)

3. **Create posts** — Call `create_posts` with:
   - `socialMediaId`: account ID from step 1
   - `content`: the post text/caption
   - `scheduledAt`: ISO 8601 datetime (required unless status is DRAFT)
   - `mediaItems`: array of `{key, type, sortOrder}` from uploaded media
   - `status`: SCHEDULED (default) or DRAFT
   - `firstComment`: optional first comment text, posted automatically after publishing (supported on X, Instagram, Facebook, YouTube, Threads, and TikTok — TikTok: Business accounts only, max 150 chars, comments must be enabled)
   - `controls`: platform-specific settings (see below)
   - You can batch up to 15 posts in a single call — great for content calendars
   - Don't schedule to a `DISABLED` account — the API rejects it with HTTP 400 `socialMediaDisconnected`. Saving as DRAFT is still allowed. Check `connectionStatus` from step 1 first.

4. **Confirm** — Show the user a summary: which accounts, what content, when scheduled.

## Platform-Specific Controls

### X (Twitter)
- `xRetweetUrl`: URL of tweet to retweet (ignores content/media)

### Instagram
- `instagramPublishType`: TIMELINE (default), STORY, or REEL
- `instagramPostToGrid`: boolean, default true (for Reels)
- `instagramCollaborators`: array of usernames to invite as collaborators

### Facebook
- `facebookContentType`: POST (default), REEL, or STORY
  - POST: up to 10 photos OR 1 video
  - REEL: 1 video only
  - STORY: 1 image OR 1 video
- `facebookReelsCollaborators`: array of usernames (for Reels)

### TikTok
- `tiktokPrivacy`: **deprecated** — TikTok videos use the account default privacy (no per-post control) and photos default to public; use `tiktokIsDraft` for private posts
- `tiktokIsDraft`: boolean, default false
- `tiktokAllowComments`: boolean, default true
- `tiktokAllowDuet`: boolean, default true
- `tiktokAllowStitch`: boolean, default true
- `tiktokBrandOrganic`: boolean, default false
- `tiktokBrandContent`: boolean, default false
- `tiktokAutoAddMusic`: boolean, default false
- `tiktokIsAigc`: boolean, default false (declare video as AI-generated content)

### YouTube
- `youtubeTitle`: defaults to first 100 chars of content
- `youtubePrivacy`: PUBLIC (default), PRIVATE, or UNLISTED
- `youtubeTags`: array of tag strings
- `youtubeCategoryId`: YouTube category ID
- `youtubeIsShort`: boolean, default true
- `youtubeMadeForKids`: boolean, default false (COPPA compliance)
- `youtubePlaylistId`: playlist ID (use `list_youtube_playlists` to find it)
- `youtubeThumbnailKey`: S3 media key for custom video thumbnail (upload via `upload_media` or `get_upload_urls`; JPEG/PNG recommended, max 2MB, min 640px wide, 1280x720 ideal; requires phone-verified YouTube channel)

### Pinterest
- `pinterestBoardId`: **required** — use `list_pinterest_boards` to get the `boardId`
- `pinterestLink`: destination URL when pin is clicked
- Content is parsed as: first line = pin title (max 100 chars), remaining lines = description (max 800 chars)
- Carousel: 2-5 static images (no videos)

### Google Business Profile
- `gbpLocationId`: **required** — use `list_gbp_locations` to get the `locationId`
- `gbpTopicType`: STANDARD (default), EVENT, or OFFER
- `gbpCallToActionType`: BOOK, ORDER, LEARN_MORE, SIGN_UP, CALL, or SHOP
- `gbpCallToActionUrl`: URL for the CTA button (not needed for CALL, ignored for OFFER)
- `gbpEventTitle`: title for EVENT/OFFER posts (max 58 chars)
- `gbpEventStartDate`: start date (ISO 8601, required for EVENT/OFFER)
- `gbpEventEndDate`: end date (ISO 8601, required for EVENT/OFFER)
- `gbpOfferCouponCode`: coupon code (OFFER only)
- `gbpOfferRedeemUrl`: redemption URL (OFFER only)
- `gbpOfferTerms`: terms and conditions (OFFER only)
- Content max: 1,500 chars. Media: up to 5 images or 1 video. Standard posts expire after 6 months; EVENT/OFFER posts expire at end date.

### LinkedIn
- `linkedinAttachmentKey`: S3 key for document attachment (for document posts)
- `linkedinAttachmentTitle`: display title for the document (default "Document")
- Cannot mix documents with regular image/video media
- Supported document formats: PDF, DOC, DOCX, PPT, PPTX (max 60MB)

## Other Actions

- **View posts**: `list_posts` — filter by `platforms` (comma-separated), `statuses` (DRAFT, SCHEDULED, PUBLISHED, FAILED), `from`/`to` dates, with pagination (`page`, `limit` up to 50). Failed or missed posts include a `lastError` with a `code` — e.g. `MISSED_DISCONNECTED` (the account was disconnected when the post was due) or `MISSED_NOT_PUBLISHED` (missed its slot by more than the 2h grace window)
- **Post analytics**: `get_post_analytics` — fetch published posts with performance metrics. Requires `startDate` and `endDate` (ISO 8601). Optional filters: `platforms`, `socialMediaIds`. Returns impressions, reach, likes, comments, shares, totalInteractions, plus an `extras` object with platform-specific metrics. Supported: Instagram, Facebook, TikTok, Threads, YouTube, LinkedIn (company pages), Pinterest (Business accounts). Pinterest `extras` include `pin_clicks`, `outbound_clicks`, `saves_90d`, `save_rate_90d`; video pins also surface `mrc_views`, `views_10s`, `avg_watch_time`, `v50_watch_time`, `video_starts`, `quartile_95_views`. Video posts also include normalized watch-time on `latestMetric`: `avgWatchTimeSeconds`, `totalWatchTimeSeconds`, `videoViews` (Facebook, Instagram Reels, YouTube, Pinterest, LinkedIn company pages, TikTok); TikTok also exposes `total_time_watched`, `average_time_watched`, and `full_video_watched_rate` in `metric.extras`. Note: LinkedIn personal accounts are excluded; Pinterest saves are reported as a rolling 90-day window because Pinterest's API does not expose lifetime save totals (all other Pinterest metrics are lifetime); `latestMetric` is null if metrics haven't been fetched yet; metric values are strings (bigint). Keep date ranges reasonable as there's no pagination.
- **Follower history**: `get_follower_history` — daily follower-count snapshots for one account (`socialMediaId`), plus `currentFollowerCount` and a signed `delta` over the range. Optional `from`/`to` (ISO 8601); defaults to the last 90 days, capped at 365. Tracking is forward-only — `trackingStartedAt` marks when recording began, with no data before it; counts are strings (bigint). Coverage: Facebook Pages, Instagram, YouTube, Pinterest, Threads, Bluesky, Telegram, LinkedIn company pages, and TikTok (not X or personal Facebook)
- **Delete a post**: `delete_post` with the post ID
- **Connect new accounts**: `generate_connect_link` — creates a secure URL to share with clients/collaborators to connect their accounts. Set `expiryDays` (1-30) and optionally `sendEmail` with an `email` address
- **Pinterest boards**: `list_pinterest_boards` — get board IDs before creating Pinterest posts
- **YouTube playlists**: `list_youtube_playlists` — get playlist IDs for adding videos to playlists
- **GBP locations**: `list_gbp_locations` — get location IDs before creating Google Business Profile posts

## Tips

- Always confirm schedule time and target accounts with the user before creating posts.
- If `list_accounts` shows an account as `DISABLED`, tell the user to reconnect it before scheduling — scheduled posts to disconnected accounts are rejected, and posts already due get marked missed.
- For content calendars, batch multiple posts in one `create_posts` call (up to 15).
- When posting to Pinterest, always fetch boards first — `pinterestBoardId` is required.
- When posting to Google Business Profile, always fetch locations first — `gbpLocationId` is required.
- Use DRAFT status if the user wants to review posts in the PostFast dashboard before they go live.
- The `firstComment` feature is useful for adding hashtags on Instagram without cluttering the caption.