sales-buffer

name	sales-buffer
description	Buffer (buffer.com) platform help — simple social media publishing/scheduling across 11 networks (Instagram, LinkedIn, TikTok, X, etc.) with queue scheduling, drafts, analytics, engagement, and link-in-bio. Two APIs: a current GraphQL developer API (Bearer key from publish.buffer.com/settings/api, plan-based rate limits, beta/free) and a deprecating legacy REST v1 (OAuth, 60/min); no webhooks. Use when building a Buffer API integration to auto-schedule posts or pull metrics, migrating a legacy v1 integration to the GraphQL API, hitting plan-based API rate limits, per-channel pricing exploding as you add accounts, the free plan's 3-channel or lifetime 8-connection cap, needing approval workflows (Team plan), Buffer lacking social listening, or choosing Free vs Essentials vs Team. Do NOT use for social media management strategy or tool selection across tools (use /sales-social-media-management), social listening (use /sales-social-listening), or influencer marketing (use /sales-influencer-marketing).
argument-hint	[describe what you need help with in Buffer]
license	MIT
version	1.0.0
tags	["sales","social-media-management","publishing","platform"]
github	https://github.com/bufferapp

Buffer Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. What are you trying to do?

   • A) Build an API integration — auto-schedule posts, manage channels, pull post metrics
   • B) Migrate a legacy v1 (api.bufferapp.com/1) integration to the new GraphQL API
   • C) Fix API rate limits / auth (Bearer key vs legacy OAuth) / the 2026 media (Assets Input) change
   • D) Understand pricing — the per-channel model, free-plan caps, Team-gated features
   • E) Configure a module — Publish/queue, Create (Ideas), Analyze, Community, approvals, Start Page
   • F) Decide if Buffer fits — vs needing social listening, agency scale, or deep collaboration

2. Which API? Build new on the GraphQL API; only touch REST v1 for an existing integration you're migrating. There are no webhooks — anything reactive must poll.

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

Step 2 — Route or answer directly

If the question is about...	Route to...
Social media management strategy or tool selection across tools	/sales-social-media-management {question}
Social listening / monitoring (Buffer has none)	/sales-social-listening {question}
Influencer marketing	/sales-influencer-marketing {question}
Connecting Buffer to other tools generically (iPaaS)	/sales-integration {question}

When routing, give the exact command, e.g. "This is a tool-selection question — run: /sales-social-media-management Buffer vs Hootsuite for a 3-client agency".

Step 3 — Buffer platform reference

Read references/platform-guide.md for the full reference — the module map (what's API vs UI-only), the per-channel pricing model (free-plan 3-channel + lifetime 8-connection caps, Team-gated approvals, no social listening), the channel/post data model with JSON shapes, and quick-start recipes (auto-schedule via GraphQL; poll metrics into a dashboard; migrate v1→GraphQL).

Read references/buffer-api-reference.md for the integration surface — the GraphQL API (developers.buffer.com, Bearer key from publish.buffer.com/settings/api, createPost mutation, plan-based rate limits across 15-min/24-hr/30-day windows, the 2026-05 Assets-Input migration) and the legacy REST v1 (api.bufferapp.com/1/, OAuth, /updates/create.json, 60/min). Note: no webhooks on either.

Answer using only the relevant section. Don't dump the full reference.

Step 4 — Actionable guidance

Focus on the user's specific situation:

• Build on GraphQL; v1 is sunsetting. New work uses the GraphQL API with a Bearer API key from publish.buffer.com/settings/api. Touch REST v1 only to migrate an existing integration.
• There are no webhooks — poll. For "did it publish?" / metrics, poll on a cadence that respects the 15-min/24-hr/30-day rate windows (e.g. hourly), and cache. Don't tight-loop.
• Mind the 2026 media change. The Assets Input format changed 2026-05-25; the legacy media format now fails. Update media submission per the migration guide.
• Cost is per channel. Each connected account is billed — 10 channels on Essentials ≈ $600/yr. For many accounts/clients, weigh flat-rate tools (route to /sales-social-media-management).
• Know the free-plan traps. 3 active channels, 10 queued posts/channel, and a lifetime cap of 8 unique channel connections (counts every account ever connected, even if disconnected).
• Buffer doesn't do listening. If they need monitoring/sentiment, that's a separate tool (/sales-social-listening); approvals/collaboration need the Team plan.

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research (2026-06) — review these, especially pricing and the API beta status, which change.

1. No webhooks. Both APIs are pull-only — reactive flows must poll within the rate windows. Don't promise event pushes.
2. Two APIs, build on GraphQL. The current developer API is GraphQL (Bearer key); the legacy REST v1 (api.bufferapp.com/1, OAuth, 60/min) is being deprecated.
3. 2026-05-25 Assets Input migration. The old media-submission format now fails — update to the new Assets Input or image/video posts break.
4. Per-channel pricing compounds. $5 (Essentials) / $10 (Team) per channel/mo — agencies with many accounts pay a lot; model the real cost before committing.
5. Free-plan caps are sneaky. 3 active channels, 10 queued posts/channel, and a lifetime 8-unique-connection ceiling that counts disconnected channels too.
6. Approvals & some scheduling features are Team-gated. Approval workflows, first-comment scheduling, and hashtag manager aren't on lower tiers.
7. No social listening. Buffer is publish + light engagement/analytics only — pair with a listening tool for monitoring.
8. Network APIs break features. Auto-publishing Stories/Reels/first-comments depends on each network's API — features can stop working when Instagram/TikTok/X change theirs.

Related skills

• /sales-social-media-management — Social media management strategy and tool selection across tools (Buffer vs Hootsuite/Later/Agorapulse; per-channel cost trade-offs)
• /sales-social-listening — Social listening/monitoring strategy (Buffer has none — pair a dedicated tool)
• /sales-influencer-marketing — Influencer discovery, vetting, and campaign strategy
• /sales-integration — Connecting Buffer to other tools via Zapier/Make (no native webhooks)
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code

Examples

Example 1: Auto-schedule posts from my app (developer/automation)

User says: "When I publish a blog post, I want it auto-scheduled to my Buffer channels via the API." Skill does: Walks Recipe 1 — POST a GraphQL createPost mutation to the Buffer API with channelIds, text, scheduledAt, and status: scheduled, authenticated with a Bearer API key from publish.buffer.com/settings/api. Flags building on GraphQL (not the deprecating REST v1), the new Assets Input format for media (legacy fails since 2026-05-25), and that there are no webhooks, so confirm publish status by polling. Result: Blog posts auto-schedule to Buffer.

Example 2: My agency's Buffer bill keeps climbing

User says: "We manage 12 client accounts in Buffer and the cost keeps going up — is there a cheaper way?" Skill does: Explains Buffer prices per channel ($5–$10/channel/mo), so 12+ accounts compound fast, and approvals are Team-gated. Suggests auditing active vs idle channels and weighing flat-rate alternatives, then routes the comparison: "run: /sales-social-media-management Buffer per-channel cost vs flat-rate tools for a 12-client agency." Result: User understands the cost driver and gets a path to the selection decision.

Example 3: Can Buffer tell me what people are saying about my brand?

User says: "Does Buffer do social listening so I can track brand mentions?" Skill does: Clarifies Buffer has no social listening — it's publishing + light engagement/analytics. Recommends pairing a dedicated listening tool and routes: "run: /sales-social-listening track brand mentions and sentiment." Notes Buffer's Community module only handles comments on your own posts, not monitoring. Result: User sets the right expectation and gets pointed to the right tool.

Troubleshooting

My API calls fail with auth errors

Symptom: 401/unauthorized, or a v1 token doesn't work on the new API. Cause: Mixing the two APIs — the GraphQL API uses a Bearer API key (from publish.buffer.com/settings/api), while legacy v1 uses OAuth access_token (and the auth code is valid only 30 seconds). They aren't interchangeable. Solution: For new builds use the GraphQL API with Authorization: Bearer YOUR_KEY. For v1, complete the OAuth exchange quickly (code expires in 30s) and pass ?access_token=. Don't reuse a v1 token against GraphQL.

My image/video posts started failing

Symptom: Media posts that worked before now error. Cause: The Assets Input migration (2026-05-25) — mutations using the legacy assets input format now fail. Solution: Update media submission to the new Assets Input format per Buffer's migration guide. Re-test image, video, and threaded posts after switching.

I'm hitting rate limits / can't get real-time updates

Symptom: Rate-limit errors, or you want instant publish/engagement events. Cause: The API meters requests per 15-min/24-hr/30-day windows (and caps API keys/OAuth clients 1–5 by plan), and Buffer has no webhooks. Solution: Poll on a cadence that fits the windows (e.g. hourly for metrics, not every minute), cache results, and back off on errors. If you need higher limits, move up a plan; there is no webhook option, so design around polling.