---
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.