buffer

Buffer ソーシャルメディア投稿のスケジュール設定

セットアップ

BUFFER_API_TOKEN 環境変数が必要です。次のページで生成してください。 https://publish.buffer.com/settings/api

API 呼び出しを行う前に、トークンが設定されていることを確認してください。

if [ -z "$BUFFER_API_TOKEN" ]; then
  echo "Error: BUFFER_API_TOKEN is not set. Get your token at https://publish.buffer.com/settings/api"
  exit 1
fi

API の設定

• エンドポイント： https://api.buffer.com
• メソッド： POST（すべてのリクエストは GraphQL です）
• Content-Type： application/json
• 認証： Authorization: Bearer $BUFFER_API_TOKEN
• User-Agent： Mozilla/5.0 — Cloudflare による 403 ブロックを回避するために必要です

Curl テンプレート

すべての API 呼び出しは、次のパターンに従います。

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}'

読みやすい出力にするため、常に jq にパイプしてください。エラーを検出するには jq -e を使用します。

重要： GraphQL 変数（例：$input）を使うクエリでは、シングルクォート内であってもシェルによって $input が展開される場合があります。これを避けるには、-d @file を使って一時ファイルを使用してください。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}
EOF

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

変数を含まない単純なクエリでは、-d に直接インラインで指定できます。

モードの判定

ユーザーの意図を解析し、実行する操作を判断します。

意図	モード	例
組織を一覧表示する	organizations	「Buffer の組織を表示して」
チャンネルを一覧表示する	channels	「どのチャンネルを持っている？」
投稿を表示する	posts	「スケジュール済みの投稿を表示して」
テキスト投稿を作成する	create-post	「『…』というツイートをスケジュールして」
Twitter/X のスレッドを作成する	create-thread	「X にスレッドを投稿して…」
画像投稿を作成する	create-post	「この画像を Instagram に投稿して」
アイデアを保存する	create-idea	「…についてのアイデアを保存して」
アカウント情報を取得する	account	「Buffer アカウントを表示して」

ほとんどの操作には organizationId が必要です。ユーザーが指定していない場合は、まず組織を取得してください。組織が 1 つだけの場合は、自動的にそれを使用します。

モード：組織を取得する

ユーザーの組織を取得します。通常、最初に必要となる呼び出しです。

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

後続の呼び出しで使うため、レスポンスから organizationId を保存してください。

モード：チャンネルを取得する

組織のチャンネル（ソーシャルメディアアカウント）を一覧表示します。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetChannels($input: ChannelsInput!) { channels(input: $input) { id name displayName service avatar isQueuePaused } }", "variables": {"input": {"organizationId": "<ORG_ID>"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

チャンネル名、サービス（例：twitter、instagram、linkedin）、キューの状態がわかる形式で結果を表示してください。

モード：投稿を取得する

フィルタリング、並べ替え、ページネーションを指定して投稿をクエリします。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id text status dueAt sentAt createdAt channelService externalLink } cursor } pageInfo { hasNextPage endCursor } totalCount } }", "variables": {"input": {"organizationId": "<ORG_ID>", "filter": {"status": "scheduled"}, "sort": {"field": "dueAt", "direction": "desc"}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

利用可能なフィルターフィールド（status、channelIds、日付範囲）、並べ替えオプション、ページネーションの詳細については、references/api-reference.md を参照してください。

モード：テキスト投稿を作成する

テキスト投稿を作成してスケジュールします。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

必須フィールド

• channelId（String!）：投稿先のチャンネル
• text（String!）：投稿内容

スケジュール設定オプション

• schedulingType：automatic（Buffer が投稿時刻を選択）または notification（リマインダーを送信）
• mode：投稿が公開されるタイミングを制御します。実際の GraphQL enum は ShareMode で、値は 4 つのみです：addToQueue、shareNow、shareNext、customScheduled（d に注意してください。customSchedule ではありません）。recommendedTime という値はありません。どこかで参照されている場合は誤りです。不明な場合は、スキーマのイントロスペクション（__type(name: "ShareMode") { enumValues { name } }）で確認してください。
• dueAt（String）：ISO 8601 形式の日時。mode が customScheduled の場合に必須です。例："2026-03-15T14:00:00Z"

フィールドの定義と enum の値について詳しくは、references/api-reference.md を参照してください。

レスポンスの処理

mutation は union 型を返します。成功とエラーの両方を必ず確認してください。

# Check if the response contains an error
result=$(curl -s -X POST https://api.buffer.com -H "User-Agent: Mozilla/5.0" ...)
echo "$result" | jq -e '.data.createPost.message' > /dev/null 2>&1 && {
  echo "Error: $(echo "$result" | jq -r '.data.createPost.message')"
} || {
  echo "$result" | jq '.data.createPost.post'
}

LinkedIn ページ（企業／ショーケースページ）へのメンション

予約投稿で LinkedIn の企業ページまたはショーケースページに @メンションするには、ページの完全な LinkedIn URL を投稿の text に直接貼り付けます。LinkedIn は公開時に、認識した企業／ショーケースページの URL を適切な @メンションチップに変換します。組織 ID を調べたり、アノテーションのペイロードを作成したりする必要はありません。

例：

https://www.linkedin.com/company/<slug>
https://www.linkedin.com/showcase/<slug>

動作確認済みの例：https://www.linkedin.com/showcase/docusigndevs（Docusign Developers のショーケースページ）。

より低レベルの仕組み（通常は不要）： スキーマでは metadata.linkedin.annotations（型は AnnotationInputLinkedIn）も公開されており、text 内の正確な部分文字列（start、length）を、明示的な id／entity（LinkedIn の組織 URN）、link、localizedName、vanityName に関連付けられたメンションとして指定できます。Buffer 独自の投稿作成画面では、メンション選択機能の実装にこの方法を使っていると思われます。この API には、ページ URL やバニティ名を組織 URN に変換する公開クエリがないため、API だけでこのペイロードを自分で作成するのは現実的ではありません。ページ URL を text に貼り付ける方法が確実です。

モード：Twitter/X スレッドの作成

Twitter/X のスレッドは、createPost ミューテーションの metadata.twitter.thread フィールドを使って作成します。スレッドは ThreadedPostInput オブジェクトの配列で、各オブジェクトには text フィールド（および任意の assets）があります。

重要： スレッドの最初のツイートは thread 配列に含める必要があります。トップレベルの text フィールドも必須ですが、Buffer は UI でツイートをすべて表示する際にスレッド配列を使用します。最初のツイートについては、両方の場所に同じテキストを含めてください。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<FIRST_TWEET_TEXT>", "schedulingType": "automatic", "mode": "addToQueue", "metadata": {"twitter": {"thread": [{"text": "<FIRST_TWEET_TEXT>"}, {"text": "<SECOND_TWEET_TEXT>"}, {"text": "<THIRD_TWEET_TEXT>"}]}}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

スレッドの構成

• トップレベルの text：必須です。最初のツイートのテキストを使用します。
• metadata.twitter.thread：ThreadedPostInput オブジェクトの配列です。各オブジェクトには次の項目があります。
  • text（String）：ツイートの内容
  • assets（AssetsInput、任意）：そのツイートに添付する画像
• thread 配列の最初の要素は、トップレベルの text と一致させてください（Buffer ではこれがツイート 1 として表示されます）。
• 2 番目以降の要素は、スレッド内の返信ツイートになります。

スレッドのヒント

• スレッド内の各ツイートは、Twitter の文字数制限（280 文字）を守る必要があります。
• スレッドは単一のまとまりとして予約され、一度にすべて投稿されます。
• 各 ThreadedPostInput の assets フィールドを使って、個々のツイートに画像を添付できます。

モード：画像投稿の作成

テキスト投稿と同じですが、画像 URL を含む assets フィールドを追加します。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue", "assets": {"images": [{"url": "<IMAGE_URL>"}]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

画像は一般公開されている URL である必要があります。images 配列には複数の画像を含められます。

モード：アイデアの作成

後で使うためにアイデアを保存します。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreateIdea($input: CreateIdeaInput!) { createIdea(input: $input) { ... on Idea { id content { title text services } } } }", "variables": {"input": {"organizationId": "<ORG_ID>", "content": {"title": "<IDEA_TITLE>", "text": "<IDEA_BODY>", "services": ["twitter", "linkedin"]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

IdeaContentInput フィールド（title、text、services、tags）の詳細は、references/api-reference.md を参照してください。

注： タグには id と color フィールドを持つ既存のタグオブジェクトが必要です。使用する前に、既存のタグを取得してください。

モード：アカウントの取得

注： アカウント情報の完全なクエリ（id、name、email、timezone）は、標準の API トークンスコープでは失敗します。アカウントの本人確認には、代わりに Get Organizations を使用してください。

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

モード：既存の投稿の編集

editPost ミューテーションを使って、予約投稿を更新します（たとえば、実際のリンクが利用可能になった後で、LinkedIn の最初のコメントにリンクを追加する場合）。

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation EditPost($input: EditPostInput!) { editPost(input: $input) { ... on PostActionSuccess { post { id status dueAt channelService } } ... on MutationError { message } } }", "variables": {"input": {"id": "<POST_ID>", "text": "<FULL_POST_TEXT_AGAIN>", "metadata": {"linkedin": {"firstComment": "<COMMENT_TEXT>"}}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

注意点： EditPostInput では text は任意であり、変更しようとしていない場合でも、text を含めずに metadata（またはその他のフィールド）を送信すると、editPost はリクエストを拒否します。"Invalid post: Post must have either text or media." というエラーになります。実際に更新するフィールドとあわせて、既存の text 全体を必ず再送信してください。

よくあるワークフロー

投稿を予約する

ユーザーが投稿の予約を希望する場合の複数ステップのワークフローです。

1. 組織を取得する → organizationId を抽出します
2. チャンネルを取得する → 利用可能なチャンネルを表示し、ユーザーに選んでもらいます（またはサービス名で照合します）
3. 投稿を作成する → 選択した channelId と投稿内容を使用します

ユーザーがサービスを指定した場合（例：「Twitter に投稿」）、チャンネルの service フィールドと照合します。

キューを確認する

1. 組織を取得する → organizationId を抽出します
2. filter: { status: "scheduled" } と sort: { field: "dueAt", direction: "asc" } を指定して 投稿を取得する
3. チャンネル情報とともに、日付ごとにグループ化した投稿を表示します

アイデアを出し合って保存する

1. 組織を取得する → organizationId を抽出します
2. ユーザーがアイデアの内容を作成するのを支援します
3. タイトル、テキスト、タグ、対象サービスを指定して アイデアを作成する

スキーマのイントロスペクション

変更を試みる前や、不確かなフィールドをクエリする前に、まずスキーマをイントロスペクションしてください。推測しないでください。API の範囲は限られています。

利用可能なすべてのミューテーションを一覧表示する：

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { mutationType { fields { name } } } }"}' | jq '[.data.__schema.mutationType.fields[].name]'

利用可能なすべてのクエリを一覧表示する：

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { queryType { fields { name } } } }"}' | jq '[.data.__schema.queryType.fields[].name]'

特定の型のフィールドを調べる：

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __type(name: \"<TYPE_NAME>\") { fields { name type { name kind } } } }"}' | jq '.data.__type.fields[]'

エラー処理

GraphQL エラー

すべてのレスポンスで、トップレベルの errors 配列を確認してください。

result=$(curl -s -X POST https://api.buffer.com ...)
errors=$(echo "$result" | jq -r '.errors // empty')
if [ -n "$errors" ]; then
  echo "GraphQL Error:"
  echo "$result" | jq '.errors[].message'
  exit 1
fi

ミューテーションエラー

ミューテーションはユニオン型を返します。必ず MutationError バリアントを処理してください。

{
  "data": {
    "createPost": {
      "message": "Validation failed: text is required"
    }
  }
}

よくある問題

• 403 Forbidden（エラーコード 1010）：Cloudflare がリクエストをブロックしています。すべての curl 呼び出しに -H "User-Agent: Mozilla/5.0" を必ず含めてください。
• 401 Unauthorized：トークンが無効か、有効期限が切れています。https://publish.buffer.com/settings/api で再生成してください。
• organizationId がない：ほとんどのクエリには組織 ID が必要です。まず組織を取得してください。
• channelId が無効：チャンネルが存在し、現在の組織に属していることを確認してください。
• dueAt が過去：customScheduled を使用する場合、dueAt は未来の日時である必要があります。