BulkPublish

View saved version →

---
name: brand-voice-editor
description: Edit social media content into a consistent brand voice while preserving facts and preparing it for BulkPublish platforms.
---

# Brand Voice Editor

Improve social copy against a supplied brand voice, examples, audience, and objective without inventing a new identity or changing the underlying claims.

## Workflow

1. Extract voice traits, banned language, preferred terminology, reading level, and CTA style from the user's guidance.
2. Edit for clarity, confidence, specificity, inclusivity, and natural platform fit.
3. Preserve links, product names, factual qualifiers, and required disclosures.
4. Produce a master version and platform-specific variants where character limits or norms differ.
5. Validate the variants with `platform-reference` before placing them into BulkPublish `platformContent` or a draft.

Flag missing voice guidance as an assumption and do not publish or schedule until the user approves materially changed claims.

View saved version →

---
name: campaign-performance-report
description: Produce campaign performance reports from BulkPublish analytics with platform-aware metrics, caveats, and recommendations.
---

# Campaign Performance Report

Turn a date range, campaign label, group of channels, or post list into an evidence-based report.

## Workflow

1. Define the reporting window, campaign scope, objectives, comparison period, and audience for the report.
2. Use BulkPublish `list_posts`, `get_analytics`, and `get_post_metrics` as appropriate.
3. Check `metricsSupported` and `supportedMetrics` before reporting any per-platform metric; an unsupported metric is not a measured zero.
4. Keep BulkPublish `linkClicks` separate from platform-native `clicks` and disclose tracking limitations.
5. Summarize results by platform, format, theme, and timing, then give prioritized recommendations linked to observed evidence.

Do not infer conversions, sentiment, reach, or attribution that BulkPublish does not provide.

View saved version →

---
name: content-repurposing
description: Repurpose a source article, newsletter, transcript, or announcement into a coordinated BulkPublish social content package.
---

# Content Repurposing

Extract the source's durable ideas and create original, platform-native social posts without copying unsupported claims or excessive source text.

## Workflow

1. Identify the source's audience, key points, evidence, links, ownership, and desired outcome.
2. Select a varied package of hooks, summaries, quotes, questions, carousels, short-form video concepts, and CTAs appropriate to the available assets.
3. Adapt each item with `platform-content-adapter`, preserving attribution and the canonical link where relevant.
4. Use `media-preflight` for any derived image or video plan.
5. Prepare the package as BulkPublish drafts, scheduled posts, or a CSV/API execution plan according to the user's request.

Do not fabricate quotations, transcript wording, statistics, or media that was not supplied.

View saved version →

---
name: get-analytics
description: Pull analytics, engagement metrics, and performance data from BulkPublish. Use when the user asks about post performance or engagement.
---

# BulkPublish — Analytics Reference

## Tools

| Tool | Use for | Key params |
|---|---|---|
| `get_analytics` | Overall summary for a date range | `startDate`, `endDate` (ISO dates) |
| `get_post_metrics` | Single post engagement | `postId` |
| `view_analytics` | Same summary as an interactive dashboard | same as `get_analytics` |
| `list_posts` | Find posts to analyze | `status`, `approvalStatus`, `from`, `to`, `channelId`, `search` |

## get_analytics response shape

Returns: total posts, status breakdown (any of the 7 post statuses: draft, scheduled, publishing, published, processing, failed, partial), per-platform counts, daily post counts for the range.

Posts also carry `approvalStatus` (`none` default | `pending` | `approved` | `rejected`), which is separate from `status` — filter `list_posts` with `approvalStatus: "pending"` to see the team approval queue. Pending and rejected posts never publish on their own.

## get_post_metrics response shape

Returns per-platform: likes, comments, shares, impressions, reach, clicks, saves, videoViews, engagementRate.

Plus `linkClicks` (and `totals.linkClicks` / `totalLinkClicks`): clicks on
bulkpubli.sh short links, measured by BulkPublish rather than reported by the
platform.

### Never report a 0 without checking `supportedMetrics` first

Every platform entry carries two support fields:

- `metricsSupported` — `false` when the platform has no per-post statistics API at all.
- `supportedMetrics` — the list of metric keys that platform *can* populate.

All metric columns are stored as integers defaulting to `0`, so a metric the
platform never reports is indistinguishable from a real zero **unless you read
`supportedMetrics`**. A key that is not in that list is **not a measurement** —
say "not reported by <platform>" or show a dash. Reporting it as `0` tells the
user their post got zero engagement when the platform simply has no such metric.

### `linkClicks` is the one metric every platform has

`linkClicks` is measured by BulkPublish, not the platform, so it is populated
even for the platforms in the "reports nothing" row below, and `supportedMetrics`
always contains it. Two rules when reporting it:

- **Never add it to `clicks`/`totalClicks`.** Those are the platform's own click
  figures. One visit can register in both, so summing them double-counts.
- **A 0 here is ambiguous in a specific way**: it means no tracked clicks, which
  also happens when the organization has link tracking switched off, when the
  post contained no links, or when shortening was skipped on that channel for
  exceeding its character limit. Bot and link-preview traffic is excluded by
  design. Say "no tracked link clicks" rather than "nobody clicked".

| Platform | Reports | Never reports |
|---|---|---|
| X | impressions, likes, comments, shares, saves (bookmarks) | reach, clicks, video views |
| YouTube | impressions, video views, likes, comments | reach, shares, saves, clicks |
| Instagram | impressions, reach, likes, comments, shares, saves | clicks, video views |
| Facebook | likes, comments, shares + impressions, reach, clicks¹ | saves, video views |
| LinkedIn (company pages) | impressions, reach, likes, comments, shares, clicks | saves, video views |
| TikTok | impressions, video views, likes, comments, shares | reach, saves, clicks |
| Threads | impressions, likes, comments, shares | reach, saves, clicks, video views |
| Pinterest | impressions, clicks, saves, likes, comments, video views | reach |
| Bluesky | likes, comments, shares, saves (bookmarks) | impressions, reach, clicks, video views |
| Mastodon | likes, comments, shares | everything else |
| Discord | likes (reaction counts), comments (thread replies) | everything else |
| Google Business, Telegram, Tumblr | *nothing* | — |
| LinkedIn personal profiles | *nothing* | — |

¹ Facebook's impressions/reach/clicks come from Page Insights and need the
`read_insights` permission. Without it they stay `0` — "may not be readable",
which is neither a dash nor a trustworthy figure.

`engagementRate` is derived from impressions, so it exists only where
impressions do — it is always `0` for Bluesky and Mastodon.

### Two more reasons a figure can legitimately be 0

- **Not synced yet.** Figures come from a snapshot refreshed every 6 hours, not a
  live read. A just-published post appears immediately with zeros.
- **Metrics sync switched off.** X reads are billed, so per-post sync is opt-in
  per channel and runs at most weekly. The engagement response lists affected
  channels in `metricsDisabledChannels`; until the user enables it on the
  Channels page, every X figure stays 0 and refreshing cannot change that.

## Patterns

- "How did my posts do this week?" → `get_analytics` with last 7 days
- "Which post got the most likes?" → `list_posts` (status: "published") then `get_post_metrics` for each
- Date params are ISO date strings: "2026-04-01", not datetime

View saved version →

---
name: hashtag-keyword-research
description: Research social media keywords and hashtag sets for campaign content, then prepare BulkPublish-ready platform variants.
---

# Hashtag and Keyword Research

Build relevant, audience-oriented keyword and hashtag recommendations for content that will be published through BulkPublish.

## Workflow

- Start with the topic, audience, intent, geography, platform targets, and campaign objective.
- Separate branded, topic, community, discovery, and campaign hashtags; avoid irrelevant or deceptive tags.
- Keep recommendations platform-specific and within each platform's caption or post limits.
- Return a reusable hashtag set plus a restrained set for each post, not a long undifferentiated list.
- Use `platform-content-adapter` to place the selected terms naturally in each variant.

Before execution, check the target channels with `manage-channels` and prepare the final copy for BulkPublish `platformContent` or drafts. Do not claim search volume or trend status without a source.

View saved version →

---
name: influencer-campaign-planner
description: Plan influencer and creator social campaigns with deliverables, usage guidance, disclosure needs, and BulkPublish execution steps.
---

# Influencer Campaign Planner

Create an execution-ready creator campaign brief without assuming access to creator accounts or promising outreach.

## Include

- Campaign objective, audience, creator criteria, brief, deliverables, review milestones, usage rights, disclosure language, and success metrics.
- Platform-specific post formats and media requirements from `platform-reference`.
- A content handoff that can become BulkPublish drafts or scheduled posts on the user's connected channels.
- Approval checkpoints before paid or sponsored content is published.
- Measurement mapping using `get-analytics`, including which metrics BulkPublish can and cannot report.

Treat creator selection, contracting, payment, and account access as separate actions requiring the user's direction.

View saved version →

---
name: link-tracking-review
description: Review social links, BulkPublish link-tracking settings, and tracked-click results without confusing them with platform click metrics.
---

# Link Tracking Review

Help users decide whether links should be shortened and how to interpret BulkPublish tracking results.

## Workflow

- Check destination URLs, redirects, UTM consistency, CTA alignment, and platform character limits.
- Explain the tri-state `linkTrackingOverride`: omit it to inherit organization settings, use `true` to shorten and track, or `false` to post links as written.
- Remember that shortening may be skipped when it would exceed a platform's limit.
- Use `get-analytics` to report `linkClicks` separately from platform `clicks`; describe zero tracked clicks carefully because it may mean no link, tracking off, or no measured visit.
- Prepare the chosen setting for a BulkPublish draft or post without changing organization defaults unless explicitly requested.

View saved version →

---
name: manage-channels
description: List connected social media channels and check what the caller may do with them in BulkPublish. Use when the user asks about their connected accounts.
---

# BulkPublish — Connected Channels

## Tools

| Tool | Use for | Key params |
|---|---|---|
| `list_channels` | Connected accounts as data | `active` (default true) |
| `view_channels` | The same list as an interactive view | none |

Prefer `view_channels` when the user wants to look at their accounts, and
`list_channels` when you need the IDs to build a post.

## What comes back

Each channel carries its ID, platform, account name and connection status. Use
the channel ID in `create_post` — never the account name.

The response also carries a `capabilities` object saying whether this caller may
create, publish or approve posts. Check it before attempting a write, rather
than discovering the limit from a 403.

## Reconnecting

A channel can be connected but no longer usable, because the account's
authorization expired or was revoked on the platform's side. Those channels are
flagged in the response. A publish to one will fail, so surface it before
scheduling: tell the user which account needs reconnecting and that it is done
in BulkPublish under Channels. You cannot reconnect an account from here.

## LinkedIn

A LinkedIn channel is either a personal profile or a company page
(`accountType`: `personal` / `organization`). Both are posted to the same way,
but they are gated separately — one can be unavailable while the other works.
When that is what blocks a write, the 403 `PLATFORM_DISABLED` error names the
`accountType`.

## Notes

- `active: false` includes channels the user has switched off.
- If the user has no channels, say so plainly and point them to connecting one
  in BulkPublish; do not invent channel IDs.

View saved version →

---
name: media-library
description: Upload images and video to BulkPublish and browse the media library, so files can be attached to posts. Use when the user wants to add or find media.
---

# BulkPublish — Media

## Tools

| Tool | Use for | Key params |
|---|---|---|
| `upload_media` | Add a file from a URL or local path | `url` OR `filePath`, optional `filename` |
| `list_media` | Find existing files | `search`, `type`, `page`, `limit` |
| `view_media` | Browse the library visually | `limit` |
| `create_media_upload` | Reserve a direct upload (advanced) | `contentType`, `sizeBytes` |
| `finalize_media_upload` | Register that upload (advanced) | `r2Key`, `fileName`, `mimeType`, `sizeBytes` |

For anything ordinary, use `upload_media`. The two advanced tools exist for a
large direct upload and must be used as a pair — reserve, upload, then register.
A reservation that is never registered stores nothing.

## Attaching to a post

`upload_media` returns the stored file. Pass its ID in `mediaFileIds` on
`create_post`. Upload first, then create the post — a post cannot reference a
file that does not exist yet.

## Before uploading

- Supported: JPEG, PNG, WebP, GIF, MP4, MOV, WebM. Maximum 100MB.
- Provide either `url` or `filePath`, never both.
- Check the target platforms' requirements first with `media-preflight`:
  dimensions, aspect ratio and duration limits differ per platform and per post
  type, and a file that is fine for one can be rejected by another.

## Notes

- `list_media` returns URLs and dimensions, so prefer it over re-uploading a
  file the user already has.
- Deleting media is not available here; tell the user it is done in BulkPublish.
- Uploading the same file twice stores two copies.

View saved version →

---
name: media-preflight
description: Preflight social media images and videos against BulkPublish platform, post-type, size, format, aspect-ratio, and duration requirements before publishing.
---

# Media Preflight

Catch media and metadata problems before they create failed or partial social posts.

## Checks

1. Identify each target platform and intended post type.
2. Confirm every required media item exists, is readable, and uses a supported format and size.
3. Check platform-specific constraints such as Instagram video post types, TikTok/YouTube video requirements, Pinterest titles and boards, and carousel item counts.
4. Check dimensions, aspect ratio, duration, number of files, caption length, and required `platformSpecific` fields.
5. Report pass, warning, or blocking failure for each platform, with the exact correction needed.

Consult `platform-reference` for the current BulkPublish requirements. Do not upload, create, schedule, or publish a post while a blocking preflight issue remains unless the user explicitly chooses to proceed.

View saved version →

---
name: platform-content-adapter
description: Adapt social media content for multiple platforms while preserving the message, voice, and call to action. Use when one source idea needs platform-specific versions.
---

# Platform Content Adapter

Create platform-native variants from a source message, campaign brief, article, transcript, or draft.

## Requirements

- Preserve the factual claims, intended audience, brand voice, and primary CTA.
- Tailor the hook, length, structure, vocabulary, hashtags, and media treatment to each target platform.
- Consult `platform-reference` before recommending a post type or media combination.
- Use `platformContent` when the variants will be published through one BulkPublish post. Keep the shared `content` as a sensible fallback.
- Include required platform fields such as YouTube and Pinterest titles, and exclude platforms whose media requirements are not met.
- Do not invent links, statistics, testimonials, product capabilities, or claims.

Return the adapted copy grouped by platform, with a short note for any omitted platform or required media/metadata.

View saved version →

---
name: platform-reference
description: Complete reference for all 15 BulkPublish platforms — post types, media requirements, required fields, character limits, and platformSpecific options. ALWAYS consult before creating posts.
---

# BulkPublish — Platform Reference

## Quick Rules

- **YouTube & TikTok** require video — NEVER include them for image-only posts
- **Pinterest** requires a title — set `platformSpecific.pinterest.title`
- **YouTube** requires a title — set `platformSpecific.youtube.title`
- **Instagram** defaults to `feed_photo` — set `postTypeOverrides.instagram` for video content
- Use `platformContent` for shorter text on platforms with low char limits (Bluesky 300, Pinterest/Threads/Mastodon 500)

---

## Facebook

| Field | Value |
|---|---|
| Platform key | `facebook` |
| Char limit | 63,206 |
| Title required | No |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `post` (default) | 0-10 images OR 0-1 video | Text-only OK. No mixing images+video |
| `reel` | 1 video required | Vertical short-form video |
| `story` | 1 image OR 1 video required | Disappears after 24h |

**Media specs:** Image max 10MB (jpg/png/gif/webp). Video max 2GB (mp4/mov).

**platformSpecific options:** `linkPreview.url`

---

## Instagram

| Field | Value |
|---|---|
| Platform key | `instagram` |
| Char limit | 2,200 |
| Title required | No |
| Account type | Business or Creator (personal rejected) |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `feed_photo` (default) | 1 image required | Single photo post |
| `feed_video` | 1 video required | Single video post |
| `reel` | 1 video required | Short-form video, 9:16 recommended |
| `story` | 1 image OR 1 video required | Disappears after 24h |
| `carousel` | 2-10 images/videos required | Mixed media OK |

**Media specs:** Image max 8MB (jpg/jpeg only). Video max 1GB (mp4/mov).

**platformSpecific options:**
- `collaborators` — string (comma-separated) or array of usernames, without a leading `@`. Tagged as co-authors. Post types `feed_photo`, `feed_video`, `reel` and `carousel`; ignored on `story`
- `trialReel` — boolean, trial reel (graduates based on performance)
- `thumbnailTimestamp` — number (seconds), video thumbnail offset

**IMPORTANT:** If you have video and don't set `postTypeOverrides.instagram`, it defaults to `feed_photo` and FAILS. Always set to `reel` or `feed_video` for video.

---

## X / Twitter

| Field | Value |
|---|---|
| Platform key | `x` |
| Char limit | 280 (25,000 for long posts) |
| Title required | No |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `tweet` (default) | 0-4 images OR 0-1 video | Text-only OK. No mixing images+video |
| `thread` | Per-part media | Use `postFormat: "thread"` + `threadParts` |
| `repost` | None | Reposts (retweets) an existing post; `platformSpecific.repostId` = status URL or ID; own text/media ignored |

**Media specs:** Image max 5MB (jpg/png/gif/webp), max 4. Video max 512MB (mp4/mov), max 1, max 140s.

---

## YouTube

| Field | Value |
|---|---|
| Platform key | `youtube` |
| Char limit | 5,000 (description) |
| Title required | **YES** — `platformSpecific.youtube.title` (1-100 chars) |
| Video required | **YES** — always |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `video` (default) | 1 video required | Standard upload |
| `short` | 1 video required | Vertical, under 3 minutes |

**Media specs:** Video max 128GB (mp4/mov/avi/wmv/flv/webm), max 1.

**platformSpecific options:**
- `title` — **REQUIRED**, 1-100 chars (falls back to first line of content)
- `privacyStatus` — `public` (default), `private`, `unlisted`
- `categoryId` — YouTube category ID (default 22)
- `madeForKids` — boolean (default false)
- `tags` — string array
- `playlistId` — add to playlist after upload
- `thumbnailUrl` — custom thumbnail URL

**IMPORTANT:** YouTube ONLY accepts video. Never include YouTube channel for image-only posts.

---

## TikTok

| Field | Value |
|---|---|
| Platform key | `tiktok` |
| Char limit | 2,200 |
| Title required | No (uses content) |
| Video required | **YES** (or images for slideshow) |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `video` (default) | 1 video required | Standard video upload |
| `photo_slideshow` | 1-35 images required | Auto-creates slideshow with music |

**Media specs:** Video max 4GB (mp4/mov), max 1. Image max 20MB (jpg/jpeg/webp), max 35 for slideshow.

**platformSpecific options:**
- `privacyLevel` — `SELF_ONLY` (default), `PUBLIC`, `FRIENDS`
- `disableDuet` — boolean
- `disableStitch` — boolean
- `disableComment` — boolean
- `isAigc` — boolean (AI-generated content disclosure)
- `thumbnailTimestamp` — number (seconds)

**IMPORTANT:** TikTok ONLY accepts video (or images for slideshow). Default privacy is `SELF_ONLY` — set to `PUBLIC` for visibility.

---

## LinkedIn

| Field | Value |
|---|---|
| Platform key | `linkedin` |
| Char limit | 3,000 |
| Title required | No (optional for articles/videos) |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `post` (default) | 0-1 image OR 0-1 video | Text-only OK |
| `multi_image` | 2-20 images required | Image gallery |
| `pdf_carousel` | 2-20 images required | Converted to PDF carousel |
| `article` | 0-1 image (thumbnail) | Link share, requires `platformSpecific.url` |

**Media specs:** Image max 10MB (jpg/png/gif), max 20. Video max 500MB (mp4 only), max 1, 3s-30min.

**Account types:** `personal` (member profile) or `organization` (company page). Both are connected in the dashboard and then used like any other channel — `list_channels` reports which via `accountType`.

The two run on separate LinkedIn apps (company pages use the Community Management API, which LinkedIn requires to be the only product on its application), so they are **gated separately**. Company pages and personal profiles carry separate availability. Pages can be paused — no new page connections — while personal-profile posting is fully live. When a variant is what blocks a write, the 403 `PLATFORM_DISABLED` error carries an `accountType` field naming it.

**platformSpecific options:**
- `title` — article/video title
- `description` — article description
- `url` — **REQUIRED for article type**, link URL
- `carouselTitle` — PDF carousel title

**Mentions:** write `@[Acme Corp](urn:li:organization:1337)` (Page) or `@[Jane Doe](urn:li:person:ID)` in `content`. Ask the user for the Page or person URN if they want a real mention token; this connector cannot look one up. Other channels on the same post get plain `@Acme Corp`.

---

## Pinterest

| Field | Value |
|---|---|
| Platform key | `pinterest` |
| Char limit | 500 |
| Title required | **YES** — `platformSpecific.pinterest.title` (1-100 chars) |
| Board required | **YES** — `platformSpecific.pinterest.boardId` (auto-creates "BulkPublish" board if missing) |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `pin` (default) | 1 image required | Standard pin, 2:3 ratio recommended |
| `video_pin` | 1 video required | Video pin |
| `carousel` | 2-5 images required | Multi-image pin |

**Media specs:** Image max 20MB (jpg/png/webp), max 5. 1000x1500 recommended. Video max 2GB (mp4/mov), max 1.

**platformSpecific options:**
- `title` — **REQUIRED**, 1-100 chars (falls back to first 100 chars of content)
- `description` — pin description, max 500 chars
- `link` — destination URL
- `boardId` — target board ID (ask the user which board; the ID is in the board's URL)
- `dominantColor` — hex color
- `coverImageUrl` — video pin cover image. Optional: when omitted the server uses an attached image, then the video's auto-extracted poster frame

---

## Threads

| Field | Value |
|---|---|
| Platform key | `threads` |
| Char limit | 500 |
| Title required | No |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `text` (default) | None | Text-only post |
| `image` | 1 image required | Photo post |
| `video` | 1 video required | Video post |
| `carousel` | 2-20 images/videos | Mixed media OK |
| `thread` | Per-part | Use `postFormat: "thread"` + `threadParts` |
| `repost` | None | Reposts an existing post; `platformSpecific.repostId` = numeric post ID; own text/media ignored |

**Media specs:** Image max 8MB (jpg/png), max 20. Video max 500MB (mp4/mov), max 20.

**platformSpecific options:** `quotePostId` — quote another Threads post; `topicTag` — one topic, no leading `#`, no periods/ampersands; `locationId` — numeric place ID, supplied by the user (only once the channel has granted location tagging)

---

## Bluesky

| Field | Value |
|---|---|
| Platform key | `bluesky` |
| Char limit | 300 |
| Title required | No |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `post` (default) | 0-4 images OR 0-1 video | Text-only OK. No mixing. |
| `thread` | Per-part | Use `postFormat: "thread"` + `threadParts` |
| `repost` | None | Reposts an existing post; `platformSpecific.repostId` = post URL or ID; own text/media ignored |

**Media specs:** Image max 10MB auto-resized to <976KB (jpg/png/webp), max 4. Video max 100MB (mp4 only), max 1, max 60s.

---

## Google Business Profile

| Field | Value |
|---|---|
| Platform key | `gmb` |
| Char limit | 1,500 |
| Title required | Only for events (`eventTitle`) |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `standard` (default) | 0-1 image | Business update |
| `event` | 0-1 image | Requires dates/times |
| `offer` | 0-1 image | Promotional offer |

**Media specs:** Image max 5MB (jpg/png), max 1. No video support.

**platformSpecific options:**
- `ctaType` — `BOOK`, `ORDER`, `SHOP`, `LEARN_MORE`, `SIGN_UP`, `CALL`
- `ctaUrl` — CTA destination URL (not needed for CALL)
- `eventTitle` — event title (required for event type)
- `startDate` / `endDate` — `YYYY-MM-DD` format
- `startTime` / `endTime` — `HH:MM` format
- `couponCode` — offer coupon code
- `redeemOnlineUrl` — offer redemption URL
- `termsConditions` — offer terms text

---

## Mastodon

| Field | Value |
|---|---|
| Platform key | `mastodon` |
| Char limit | 500 |
| Title required | No |

**Post types:**

| Type | Media | Notes |
|---|---|---|
| `post` (default) | 0-4 images OR 0-1 video | Text-only OK. No mixing. |
| `thread` | Per-part | Use `postFormat: "thread"` + `threadParts` |
| `repost` | None | Reposts an existing post; `platformSpecific.repostId` = post URL or ID; own text/media ignored |

**Media specs:** Image max 16MB (jpg/png/webp/avif/gif), max 4. Video max 99MB (mp4 only), max 1, max 300s.

**platformSpecific options:**
- `visibility` — `public` (default), `unlisted`, `private`, `direct`
- `spoilerText` — content warning text
- `language` — ISO 639-1 language code

---

## Discord

| Field | Value |
|---|---|
| Platform key | `discord` |
| Char limit | 2,000 |
| Title required | No |
| Target channel required | **YES** — `channelId` |

**Post types:** message with optional attachments (images/video), sent to a text channel of the connected server.

**Media specs:** up to **10 attachments**, 25MB each (Discord's limit for a non-boosted server). Images and video may be mixed.

**platformSpecific** — keyed by **channel ID**. A connected Discord "channel" in BulkPublish is an entire **server** (guild), so the message still needs a destination channel inside it:

```json
{"platformSpecific": {"discord": {"12": {"channelId": "1090123456789012345"}}}}
```

| Option | Notes |
|---|---|
| `channelId` | **REQUIRED.** The target Discord *text channel* snowflake — **not** the BulkPublish channel id used as the outer key. List postable channels via `GET /api/channels/{id}/options`. |

**Gotchas:** publishing uses a **global bot token**, not the per-user OAuth token. A failure is therefore never a re-authentication problem — reconnecting will not fix it and the channel is never flagged `needs_reconnect`. The real causes are permissions: the bot lacks access to the channel, cannot send messages there, or the channel was deleted.

---

## Telegram

| Field | Value |
|---|---|
| Platform key | `telegram` |
| Char limit | 4,096 (text) / 1,024 (media caption) |
| Title required | No |

**Post types:** text message, photo, video, or media group (up to 10 items), sent to the chat fixed when the channel was connected.

**platformSpecific:** **none.** Telegram accepts no options — there is nothing to select per post. To publish to a second channel or group, connect it as a separate BulkPublish channel.

**Media specs:** media is handed to Telegram as a **URL** rather than uploaded, and the Bot API caps download-by-URL far below its upload limits: **5MB** images (jpg/png/webp) and **20MB** video (mp4).

**Gotchas:** content is sent as **plain text with no parse mode**, so `&`, `<` and `>` are safe but Markdown you write is **not rendered** (URLs still auto-link). When a post has media and text longer than 1,024 characters, the media is sent captionless and the full text follows as a **second message** — nothing is truncated, but it arrives as two messages.

---

## Tumblr

| Field | Value |
|---|---|
| Platform key | `tumblr` |
| Char limit | 32,768 |
| Title required | No |

**Post types:** `post` — text, photo, or video post to a Tumblr blog.

**Media specs:** up to 30 images (jpg/png/gif/webp, 20MB each), OR exactly one video (mp4/mov, 500MB). A video CANNOT be combined with images in the same post.

**platformSpecific** — keyed by **channel ID**, because one Tumblr account can own several blogs:

```json
{"platformSpecific": {"tumblr": {"12": {"blogName": "myblog", "title": "Heading", "tags": ["art"], "link": "https://example.com"}}}}
```

| Option | Notes |
|---|---|
| `blogName` | Target blog. Defaults to the blog the channel was connected as. List options via `GET /api/channels/{id}/options`. |
| `title` | Rendered as a heading above the body. |
| `tags` | Array of strings, no leading `#`. Tags drive discovery on Tumblr more than on other networks. |
| `link` | Appended as a link block. |
| `sourceUrl` | Attribution URL stored as the post's source. |

---

## Snapchat

| Field | Value |
|---|---|
| Platform key | `snapchat` |
| Char limit | 160 (Spotlight description / Saved Story title fallback only) |
| Title required | No |

**Post types** (set via `postTypeOverrides.snapchat`):

| Type | Media | Notes |
|---|---|---|
| `story` (default) | exactly 1 image or video | The caption is NOT sent to Snapchat — plain stories carry no text. |
| `saved_story` | exactly 1 image or video | Title max 45 chars; defaults to the first line of the caption, truncated. |
| `spotlight` | 1 video only, 6–60s | Caption becomes the description (max 160 chars, truncated); hashtags are clickable. |

**Media specs:** exactly ONE file per post. Images jpg/png; videos mp4/mov, vertical, 5–60s (Spotlight 6–60s), max 1GB.

**platformSpecific** — keyed by **channel ID** (a flat object applies to every Snapchat channel):

```json
{"platformSpecific": {"snapchat": {"12": {"title": "Behind the scenes", "locale": "en_US", "saveToProfile": true}}}}
```

| Option | Notes |
|---|---|
| `title` | Saved Story title, max 45 chars. Defaults to the caption's first line, truncated. |
| `locale` | Spotlight locale. Default `en_US`. |
| `saveToProfile` | Spotlight only. Default `true`; `false` sends `skip_save_to_profile`. |

**Gotchas:** `_firstComment` is NOT supported. Engagement (individual comments/reactions) is not readable. Metrics ARE reported: impressions, reach, likes, comments, shares, clicks, video views.

View saved version →

---
name: schedule-post
description: Create, schedule, or publish social media posts via BulkPublish MCP. Use when the user wants to post to social media.
---

# BulkPublish — Post Creation Reference

## create_post parameters

```
content        (string, required) — post text
channels       (array, required)  — [{channelId: number, platform: string}]
                                    Get these from list_channels first
status         ("draft"|"scheduled") — default "draft"
scheduledAt    (ISO 8601 string)  — required when status is "scheduled"
timezone       (string)           — e.g. "America/New_York", "Asia/Karachi"
mediaFileIds   (number[])         — IDs from upload_media
platformContent (object)          — per-platform text: {"x": "Short", "linkedin": "Longer version"}
postTypeOverrides (object)        — per-platform format: {"instagram": "reel", "facebook": "story"}
postFormat     ("post"|"video"|"reel"|"story"|"carousel"|"thread") — "thread" requires threadParts
threadParts    (array)            — [{content: string, mediaFileIds?: number[]}], min 2 parts.
                                    EVERY part is length-checked against every target platform,
                                    not just the first — an over-long part 400s the whole request
platformSpecific (object)         — per-platform options; see the
                                    platform-reference skill. Auto-reply after
                                    publishing goes here as the top-level key
                                    "_firstComment", NOT a firstComment param:
                                    {"_firstComment": "Link in bio!"}
                                    Unsupported on discord, pinterest, tiktok,
                                    gmb, tumblr and snapchat (recorded as failed;
                                    the main post still publishes)
requestApproval (boolean)         — default false; hold a scheduled post for team
                                    approval (approvalStatus becomes "pending")
linkTrackingOverride (boolean|null) — default null; per-post override for
                                    bulkpubli.sh link tracking. true shortens the
                                    post's links and counts clicks, false posts
                                    them as written, null inherits the org setting
```

`linkTrackingOverride` is tri-state, so **omit it unless the user actually asked
for one behaviour or the other** — sending `false` is an explicit "post the links
as written" and is not the same as leaving it unset. Shortening happens at
publish time, per channel, and is **skipped** for any channel where the rewrite
would push the post past that platform's character limit: a short URL is 28
characters and can be longer than the link it replaces, so on X (280) or Bluesky
(300) tracking may silently not apply. The post still publishes, with its
original links.

Every post object returned by the API also carries the read-only approval fields
`approvalStatus` (`"none"` default | `"pending"` | `"approved"` | `"rejected"`),
`approvedBy` (string|null), `approvedAt` (date-time|null) and `rejectionReason`
(string|null). See "Team approval" below.

## Post type overrides

| Platform | Types |
|---|---|
| Instagram | `reel`, `story`, `carousel` |
| Facebook | `story`, `reel` |
| TikTok | `slideshow` |
| YouTube | `short` |
| X/Twitter | `thread` |
| Threads | `thread` |
| Bluesky | `thread` |
| Mastodon | `thread` |

## Team approval

`approvalStatus` is **orthogonal to `status`**: the scheduler skips `pending` and
`rejected` posts even when they are scheduled and overdue. Default is `"none"`.

- **Requesting approval** — pass `requestApproval: true` on `create_post` or
  `update_post` (default `false`) to hold a scheduled post for team approval;
  `approvalStatus` becomes `"pending"`. For API keys belonging to members whose
  role lacks `post:publish` (contributors), this is **forced server-side
  regardless of the flag** — their scheduled posts always land in the approval
  queue. Never tell such a user their post was scheduled: check the returned
  `approvalStatus` and say it is awaiting approval.
- **The approval queue** — `list_posts` with `approvalStatus: "pending"` (the
  filter accepts `none` | `pending` | `approved` | `rejected`), or
  `GET /api/posts?approvalStatus=pending`.
- **Approving or rejecting** — done by a teammate with an approver role (owner, admin, approver) in BulkPublish. Approval releases the post: it publishes at its scheduled time, or immediately if that time has passed. A rejected post returns to draft with a reason, and the author can edit and resubmit. You cannot approve or reject from here — say who needs to act.
- **`APPROVAL_REQUIRED`** — `publish_post` and `retry_post` return **403** with
  error code `APPROVAL_REQUIRED` for roles without `post:publish`. Do not retry:
  create/update the post with `requestApproval: true` and tell the user a
  teammate has to approve it. Publishing a pending/rejected post *as an
  approver* implicitly approves it.

## Publishing flow

- **Draft then publish**: `create_post` (status: "draft") → `publish_post` (postId)
- **Schedule for later**: `create_post` (status: "scheduled", scheduledAt: "2026-04-12T09:00:00Z")
- **Schedule with review**: `create_post` (status: "scheduled", scheduledAt: ..., requestApproval: true) → a teammate approves it in BulkPublish
- **Optimal timing**: call `get_queue_slot` (optionally pass `timezone`, default UTC) to get the best next slot. It returns `{suggestedTime, timezone}` — it does NOT take a channelId or date (any such args are ignored).
- **Retry failures**: `retry_post` (postId, optional `republish`) re-queues the
  post's `failed` platforms. A platform can also end in status `unconfirmed` —
  terminal: the publish request may have reached the platform but its response
  was lost, so the post **may already be live**; it is never auto-retried. If
  the post has unconfirmed platforms and no failed ones, `retry_post` returns
  **400** with code `UNCONFIRMED_REQUIRES_REPUBLISH` — ask the user to check
  the account on the platform, and only pass `republish: true` (default false)
  after they confirm the post is not live; it also retries the unconfirmed
  platforms and **can duplicate the post**.
- **Publish as story**: set `postTypeOverrides` to `"story"` for Facebook/Instagram/Snapchat — publishes directly as a story, no separate call needed (Snapchat stories need exactly 1 image or video and send no caption)

## Stories vs postTypeOverrides

To publish as a story, use `postTypeOverrides` at creation time:
```json
{ "postTypeOverrides": { "facebook": "story", "instagram": "story" } }
```
This publishes the post AS a story. Set it at creation time — an existing regular post cannot be turned into a story from here.

## Character limits

| Platform | Limit |
|---|---|
| X/Twitter | 280 (25,000 long posts) |
| Instagram | 2,200 |
| Facebook | 63,206 |
| LinkedIn | 3,000 |
| TikTok | 2,200 |
| YouTube | 5,000 (description) |
| Threads | 500 |
| Bluesky | 300 |
| Pinterest | 500 |
| Google Business | 1,500 |
| Mastodon | 500 |
| Snapchat | 160 (Spotlight description / Saved Story title fallback — plain stories send no text) |

## Platform media requirements

| Platform | Requires | Notes |
|---|---|---|
| YouTube | Video ONLY | Do NOT include YouTube for image-only posts |
| TikTok | Video ONLY | Or images for `photo_slideshow` type |
| Instagram | Depends on type | `feed_photo`=image, `reel`/`feed_video`=video, `carousel`=2-10 mixed |
| Pinterest | Image or video | Needs board ID in `platformSpecific` or channel default |
| Facebook/X/LinkedIn/Threads/Bluesky/Mastodon | Any or none | Text-only posts OK |
| Snapchat | Exactly 1 image or video | jpg/png or mp4/mov, vertical, 5–60s (Spotlight 6–60s video-only), max 1GB |

## Common mistakes

- `channels` takes objects `{channelId, platform}`, NOT just IDs
- Always call `list_channels` first to get valid channelId + platform pairs
- `scheduledAt` must be in the future and in ISO 8601 format
- To publish immediately: create as draft, then call `publish_post`
- `mediaFileIds` are numbers from `upload_media`, not file paths
- **Do NOT send image-only posts to YouTube or TikTok** — they will fail
- **Instagram defaults to `feed_photo`** — set `postTypeOverrides.instagram` to `reel` or `feed_video` for video
- **Pinterest needs a board ID** — set via `platformSpecific.pinterest.boardId` or it tries to auto-create one
- **Never assume a scheduled post will go out** — if the response has
  `approvalStatus: "pending"`, it is held until someone approves it. Report that,
  not "scheduled".
- **`requestApproval` defaults to `false`** and `approvalStatus` defaults to
  `"none"` — only set the flag when the user asks for review, but always read the
  response back because contributors get it forced on.
- **Do not call `publish_post` again after a 403 `APPROVAL_REQUIRED`** — the role
  cannot publish; submit for approval instead.
- **Content char limits** are enforced per-platform — use `platformContent` for shorter overrides on Pinterest (500), Bluesky (300), etc.

View saved version →

---
name: social-campaign-builder
description: Build a coordinated social media campaign with post ideas, platform variants, CTAs, media requirements, and an execution-ready BulkPublish plan.
---

# Social Campaign Builder

Turn a campaign brief into a coherent sequence of social posts rather than a list of disconnected captions.

## Workflow

1. Establish the campaign objective, audience, offer, key message, dates, channels, approval needs, and available assets.
2. Map the campaign journey: awareness, consideration, proof, conversion, and follow-up as appropriate.
3. Create a post matrix with sequence, objective, angle, hook, CTA, target platforms, post type, media, and suggested timing.
4. Write platform-specific copy or hand off each post to `platform-content-adapter` when variants are needed.
5. Validate every media and metadata requirement with `platform-reference` and `media-preflight`.

For execution, first identify valid connected channels with `manage-channels`, then create drafts or a schedule through BulkPublish. Default to drafts when the user has not explicitly requested publishing.

View saved version →

---
name: social-content-audit
description: Audit a social media library, calendar, or BulkPublish account for content quality, platform coverage, metadata, and operational risks.
---

# Social Content Audit

Assess whether a social content system is coherent, publishable, measurable, and maintainable.

## Audit areas

- Strategy: audience, pillars, objectives, cadence, and CTA coverage
- Content: hooks, voice, repetition, accessibility, disclosures, and factual risk
- Platform fit: limits, post types, media, required titles, and channel coverage using `platform-reference`
- Operations: connected channels, drafts, scheduled posts, failures, and unconfirmed states using BulkPublish tools
- Measurement: labels, date ranges, supported metrics, link tracking, and reporting readiness

Return findings as blocking issues, recommended fixes, and optional improvements. Do not mutate BulkPublish content or settings during an audit unless the user separately authorizes the changes.

View saved version →

---
name: social-content-strategy
description: Create practical social media content strategies from a business goal, audience, offer, or campaign brief. Use before drafting a sustained cross-platform content plan.
---

# Social Content Strategy

Translate the user's goal into a focused social media strategy that can be executed through BulkPublish.

## Workflow

1. Identify the objective, audience, offer or topic, proof points, call to action, timeframe, and available media.
2. Choose a small set of content pillars that support the objective; avoid generic posting plans with no audience or business rationale.
3. Recommend platform roles using the platforms connected to BulkPublish. Match the format and tone to each platform rather than treating every channel as interchangeable.
4. Define a repeatable mix of formats, hooks, CTAs, and posting cadence.
5. Return an actionable brief for each planned post: purpose, audience, angle, hook, key points, CTA, platform targets, post type, and media need.

Ask only for missing information that materially changes the strategy. Clearly label assumptions and do not publish or schedule anything unless the user asks for execution.

View saved version →

---
name: social-copy-ab-testing
description: Design controlled social copy experiments and publish or schedule test variants through BulkPublish with measurable hypotheses.
---

# Social Copy A/B Testing

Create comparable copy variants that test one meaningful variable at a time.

## Workflow

- Define the hypothesis, audience, platform, primary metric, test window, sample or posting plan, and stop condition.
- Vary one element such as hook, CTA, proof point, framing, or format; keep the rest as consistent as practical.
- Check character limits and platform requirements with `platform-reference`.
- Use separate BulkPublish posts or platform-specific content only when the comparison remains interpretable; label variants clearly.
- Use `get-analytics` after the test window and report supported metrics, sample limitations, and the winning interpretation without overstating causality.

Create drafts first unless the user explicitly authorizes scheduling or publishing.

View saved version →

---
name: social-localization
description: Localize social media content for language, region, culture, and platform while preparing safe BulkPublish variants.
---

# Social Localization

Adapt approved social content for a specified locale while preserving the intended meaning, offer, legal qualifiers, and CTA.

## Checks

- Confirm locale, audience, dialect, script, currency, date/time format, units, cultural context, and local CTA destination.
- Translate idioms, humor, hashtags, and examples for natural use instead of translating word-for-word.
- Flag terms, imagery, claims, or references that need local review.
- Keep platform limits and media requirements in view; consult `platform-reference`.
- Return locale-tagged variants suitable for BulkPublish `platformContent`, with timezone-aware scheduling guidance when requested.

Do not invent local legal approval, availability, pricing, or performance claims. Draft by default unless the user explicitly requests BulkPublish execution.

View saved version →

---
name: social-media-calendar
description: Plan, organize, and schedule a cross-platform social media calendar through BulkPublish. Use when the user wants a posting schedule, queue, or recurring cadence.
---

# Social Media Calendar

Create a calendar that is realistic for the audience, campaign, connected channels, and BulkPublish limits.

## Workflow

- Establish the date range, timezone, cadence, campaign constraints, target platforms, and approval requirements.
- Spread topics and formats across the calendar to avoid repetition and platform over-posting.
- Use `get_queue_slot` when the user wants the next optimal available slot; do not claim an optimal time without checking it.
- Check connected channels before creating a large schedule.
- Use ISO 8601 timestamps and the user's stated timezone.
- Create drafts unless the user explicitly asks to schedule or publish. When approval is requested, set `requestApproval: true` and report the returned approval state.

Before execution, validate each post with `platform-reference` and `media-preflight`. Summarize the resulting calendar with post IDs, status, times, timezone, and any posts awaiting approval.

View saved version →

---
name: social-post-review
description: Review social media drafts for clarity, tone, platform fit, compliance risks, character limits, metadata, and publishing readiness before BulkPublish execution.
---

# Social Post Review

Give an actionable review of social copy and its planned media or platform targets.

## Review areas

- Goal and audience alignment
- Hook, clarity, structure, voice, and CTA
- Factual support, disclosure, copyright, privacy, and potentially misleading claims
- Platform character limits, formatting, hashtags, links, and post type
- Media compatibility and required metadata
- Cross-platform duplication, inconsistent claims, or a CTA that does not work on the target platform

Use `platform-reference` and `media-preflight` for technical validation. Distinguish blocking issues from suggestions. Return corrected copy only when useful, and do not publish or schedule until the user approves the reviewed draft.

View saved version →

---
name: social-trend-research
description: Research timely social media themes and translate them into safe, relevant BulkPublish content opportunities.
---

# Social Trend Research

Turn current conversations, seasonal moments, and audience questions into content ideas that can be prepared and published through BulkPublish.

## Requirements

- Verify time-sensitive trends before presenting them as current.
- Distinguish an observed trend from a suggested opportunity or an inference.
- Reject trends that conflict with the brand, exploit sensitive events, or require unsupported claims.
- For each opportunity, provide the source or evidence, audience fit, recommended platforms, hook, CTA, media need, and expiry window.
- Use `platform-reference` and `media-preflight` before turning an opportunity into a BulkPublish post.

Default to a draft or content brief. Do not schedule trend content without confirming its timing and the user's approval.

View saved version →

---
name: ugc-content-planner
description: Plan user-generated-content campaigns and convert approved UGC into compliant, platform-ready BulkPublish posts.
---

# UGC Content Planner

Design a UGC pipeline from prompt and collection through permission, review, adaptation, and publication.

## Workflow

- Define the prompt, audience, submission format, collection window, moderation rules, permission record, attribution, and escalation path.
- Separate approved, pending, rejected, and unusable submissions.
- Redact private information and flag copyright, consent, safety, and disclosure issues before use.
- Prepare platform variants and validate media with `media-preflight`.
- Use BulkPublish to upload approved media and create drafts or scheduled posts; preserve a reference to the permission record in the content workflow.

Never infer permission from a public post alone and never publish pending UGC.