sales-skills/sales-buffer

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.