Back to Details

buffer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshooting

故障排查

If requests fail, run 
zero doctor check-connector --env-name BUFFER_TOKEN
or 
zero doctor check-connector --url https://api.buffer.com --method POST
Beta API. Buffer's public API is currently in beta. Personal API keys replace the legacy OAuth v1 API. Only organization owners can create keys (paid accounts: up to 5 keys, free accounts: 1 key). The legacy REST API at 
api.bufferapp.com/1/*
still exists but is not accepting new developer applications and requires OAuth — it is not used by this connector.
如果请求失败，请运行 
zero doctor check-connector --env-name BUFFER_TOKEN
或 
zero doctor check-connector --url https://api.buffer.com --method POST
Beta API。Buffer的公开API目前处于测试版。个人API密钥已取代旧版OAuth v1 API。只有组织所有者可以创建密钥（付费账户最多5个密钥，免费账户1个密钥）。旧版REST API位于 
api.bufferapp.com/1/*
仍然存在，但不再接受新的开发者应用，且需要OAuth认证——本连接器不使用该API。

How It Works

工作原理

Buffer is a social media scheduling platform. The beta API is GraphQL-only, served from a single endpoint. Every request is a 
POST
with a JSON 
{"query": "...", "variables": {...}}
body.
Account
└── Organizations
    └── Channels (Twitter, LinkedIn, Instagram, Facebook, TikTok, Threads, Mastodon, Bluesky, Pinterest, YouTube, Google Business)
        └── Posts (draft | scheduled | sent)
Base URL: 
https://api.buffer.com
Buffer是一个社交媒体调度平台。其测试版API仅支持GraphQL，通过单一端点提供服务。所有请求均为
POST
请求，请求体为JSON格式：
{"query": "...", "variables": {...}}
Account
└── Organizations
    └── Channels (Twitter, LinkedIn, Instagram, Facebook, TikTok, Threads, Mastodon, Bluesky, Pinterest, YouTube, Google Business)
        └── Posts (draft | scheduled | sent)
基础URL：
https://api.buffer.com

Authentication

身份验证

All requests require a personal API key passed as a Bearer token:
Authorization: Bearer $BUFFER_TOKEN
Content-Type: application/json
Requests without a valid key return 
401 Unauthorized
.
所有请求都需要传递作为Bearer令牌的个人API密钥：
Authorization: Bearer $BUFFER_TOKEN
Content-Type: application/json
没有有效密钥的请求将返回
401 Unauthorized
。

Environment Variables

环境变量

VariableDescription
BUFFER_TOKEN
Buffer personal API key (from Developer Dashboard)
变量名说明
BUFFER_TOKEN
Buffer个人API密钥（来自开发者控制台）

Key Operations

核心操作

All calls hit the same endpoint: 
POST https://api.buffer.com
. Change only the GraphQL document.
所有调用都指向同一个端点：
POST https://api.buffer.com
。只需修改GraphQL文档即可。

1. List Organizations

1. 列出组织

Write 
/tmp/buffer_orgs.json
:
json
{
  "query": "query GetOrganizations { account { organizations { id name } } }"
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_orgs.json
编写
/tmp/buffer_orgs.json
：
json
{
  "query": "query GetOrganizations { account { organizations { id name } } }"
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_orgs.json

2. List Channels (Connected Social Accounts)

2. 列出渠道（关联的社交账户）

Write 
/tmp/buffer_channels.json
— replace 
<organization-id>
with an id from step 1:
json
{
  "query": "query GetChannels($organizationId: String!) { channels(input: { organizationId: $organizationId }) { id name service serviceId serviceType timezone } }",
  "variables": { "organizationId": "<organization-id>" }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_channels.json
编写
/tmp/buffer_channels.json
——将
<organization-id>
替换为步骤1中获取的ID：
json
{
  "query": "query GetChannels($organizationId: String!) { channels(input: { organizationId: $organizationId }) { id name service serviceId serviceType timezone } }",
  "variables": { "organizationId": "<organization-id>" }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_channels.json

3. Create a Scheduled Post

3. 创建定时帖子

Buffer publishes the same text to one or more channels. Write 
/tmp/buffer_create_post.json
— replace 
<channel-id>
with a channel id from step 2. 
scheduledAt
is an ISO-8601 timestamp; omit it to add to the end of the queue.
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status scheduledAt text } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Launching today: our new onboarding flow. Read more at https://example.com",
      "scheduledAt": "2026-05-01T15:00:00Z",
      "status": "scheduled"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_post.json
Valid 
status
values:
  • draft
    — saved as a draft, not queued
  • scheduled
    — queued at 
    scheduledAt
  • needsApproval
    — posted to the approval queue
Buffer会将相同文本发布到一个或多个渠道。编写
/tmp/buffer_create_post.json
——将
<channel-id>
替换为步骤2中获取的渠道ID。
scheduledAt
为ISO-8601时间戳；如果省略该字段，帖子将被添加到队列末尾。
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status scheduledAt text } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Launching today: our new onboarding flow. Read more at https://example.com",
      "scheduledAt": "2026-05-01T15:00:00Z",
      "status": "scheduled"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_post.json
有效的
status
值：
  • draft
    — 保存为草稿，不进入队列
  • scheduled
    — 在
    scheduledAt
    时间进入队列
  • needsApproval
    — 进入审批队列

4. Create a Post with Media

4. 创建带媒体的帖子

Attach images or a video by passing a 
media
object. Write 
/tmp/buffer_create_image_post.json
:
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Ship log: weekly changelog is live.",
      "media": {
        "photos": [
          { "url": "https://example.com/screenshot.png", "altText": "Changelog screenshot" }
        ]
      },
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_image_post.json
For video, swap 
photos
for 
video: { url: "<url>", thumbnailUrl: "<url>" }
.
通过传递
media
对象来附加图片或视频。编写
/tmp/buffer_create_image_post.json
：
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Ship log: weekly changelog is live.",
      "media": {
        "photos": [
          { "url": "https://example.com/screenshot.png", "altText": "Changelog screenshot" }
        ]
      },
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_image_post.json
如果是视频，将
photos
替换为
video: { url: "<url>", thumbnailUrl: "<url>" }
。

5. List Pending/Scheduled Posts

5. 列出待发布/已定时的帖子

Write 
/tmp/buffer_posts.json
:
json
{
  "query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id status text scheduledAt channel { id service } } } pageInfo { hasNextPage endCursor } } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "status": ["scheduled"],
      "first": 25
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '.data.posts.edges[].node'
Change 
status
to 
["sent"]
for history, 
["draft"]
for drafts, or 
["needsApproval"]
for the approval queue.
编写
/tmp/buffer_posts.json
：
json
{
  "query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id status text scheduledAt channel { id service } } } pageInfo { hasNextPage endCursor } } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "status": ["scheduled"],
      "first": 25
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '.data.posts.edges[].node'
将
status
改为
["sent"]
可查看历史帖子，改为
["draft"]
查看草稿，改为
["needsApproval"]
查看审批队列。

6. Update a Post

6. 更新帖子

Write 
/tmp/buffer_update_post.json
— replace 
<post-id>
:
json
{
  "query": "mutation UpdatePost($input: PostUpdateInput!) { updatePost(input: $input) { id text scheduledAt } }",
  "variables": {
    "input": {
      "postId": "<post-id>",
      "text": "Updated copy.",
      "scheduledAt": "2026-05-02T15:00:00Z"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_update_post.json
编写
/tmp/buffer_update_post.json
——替换
<post-id>
：
json
{
  "query": "mutation UpdatePost($input: PostUpdateInput!) { updatePost(input: $input) { id text scheduledAt } }",
  "variables": {
    "input": {
      "postId": "<post-id>",
      "text": "Updated copy.",
      "scheduledAt": "2026-05-02T15:00:00Z"
    }
  }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_update_post.json

7. Delete a Post

7. 删除帖子

Write 
/tmp/buffer_delete_post.json
:
json
{
  "query": "mutation DeletePost($input: PostDeleteInput!) { deletePost(input: $input) { id } }",
  "variables": { "input": { "postId": "<post-id>" } }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_delete_post.json
编写
/tmp/buffer_delete_post.json
：
json
{
  "query": "mutation DeletePost($input: PostDeleteInput!) { deletePost(input: $input) { id } }",
  "variables": { "input": { "postId": "<post-id>" } }
}
bash
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_delete_post.json

8. Publish Immediately (Share Now)

8. 立即发布（立即分享）

Set 
status: "scheduled"
and 
scheduledAt
to a timestamp a few seconds in the past, or use the dedicated share mutation when available. For queue-top placement, omit 
scheduledAt
and set 
shareNext: true
in the input.
设置
status: "scheduled"
并将
scheduledAt
设置为过去几秒的时间戳，或者在专用分享突变可用时使用该突变。如果要将帖子放在队列顶部，省略
scheduledAt
并在输入中设置
shareNext: true
。

Common Workflows

常见工作流

Cross-Post to Multiple Channels

跨平台发布到多个渠道

Put all target channel IDs in the same 
channelIds
array. Buffer fans out one post per channel and returns a single parent post id.
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<twitter-channel-id>", "<linkedin-channel-id>", "<bluesky-channel-id>"],
      "text": "Launching today.",
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}
将所有目标渠道ID放在同一个
channelIds
数组中。Buffer会为每个渠道生成一个帖子，并返回一个父帖子ID。
json
{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<twitter-channel-id>", "<linkedin-channel-id>", "<bluesky-channel-id>"],
      "text": "Launching today.",
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}

Paginate Sent Posts

分页查看已发布帖子

bash
undefined
bash
undefined

First page

第一页

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '{next: .data.posts.pageInfo.endCursor, nodes: [.data.posts.edges[].node | {id, text, scheduledAt}]}'

Replace the `"first"` field in `input` with `"after": "<endCursor>"` to continue.
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '{next: .data.posts.pageInfo.endCursor, nodes: [.data.posts.edges[].node | {id, text, scheduledAt}]}'

将`input`中的`"first"`字段替换为`"after": "<endCursor>"`即可继续分页。

Guidelines

注意事项

  1. Send payloads as JSON files with 
    -d @/tmp/filename.json
    — do not inline complex GraphQL documents.
  2. Query introspection is the fastest way to discover unfamiliar fields: 
    {"query": "{ __schema { queryType { fields { name } } } }"}
    .
  3. Rate limits are per-client and rolling — personal API keys share one bucket; if you have multiple keys, create a distinct key per integration.
  4. Analytics data is not exposed in the beta API yet. For post-level stats, use Buffer's web dashboard.
  5. Do not edit posts that have already been sent — Buffer's API currently rejects 
    updatePost
    once 
    status: "sent"
    .
  6. Organization IDs are stable; cache them instead of re-querying on every request.
  1. 将请求体作为JSON文件发送，使用
    -d @/tmp/filename.json
    ——不要内联复杂的GraphQL文档。
  2. 查询自省是发现陌生字段的最快方式：
    {"query": "{ __schema { queryType { fields { name } } } }"}
    。
  3. 速率限制按客户端计算，且为滚动限制——个人API密钥共享一个限制池；如果有多个密钥，请为每个集成创建独立的密钥。
  4. 测试版API暂未开放分析数据。如需查看帖子级统计数据，请使用Buffer的网页控制台。
  5. 不要编辑已发布的帖子——一旦帖子
    status: "sent"
    ，Buffer的API会拒绝
    updatePost
    请求。
  6. 组织ID是稳定的；请缓存这些ID，不要每次请求都重新查询。