slack-api

Slack Web API

開発者が適切な Web API メソッドを見つけ、その仕様を読み、正しく呼び出せるよう支援します。Slack には family.method のドット記法（例：chat.postMessage、conversations.history）で名付けられた数百のメソッドがあり、https://slack.com/api/<method> で利用できます。すべてのメソッドのドキュメントページは固定の URL パターンに従っているため、どのメソッドの仕様も常に 1 回のフェッチで取得できます。

$0 が指定されている場合、完全な method.name（仕様を読むため Step 2 に進みます）か、family 名（索引から見つけるため Step 1 に進みます）のいずれかです。

重要なルール：

• 呼び出す前に、メソッド名と必須スコープをそのドキュメントページで確認してください。メソッド名を作り出したり、スコープを推測したりしないでください。メソッド名には family.method のドット記法を使用します。
• すべてのレスポンスにはトップレベルの ok ブール値があります。結果を使う前に必ず ok を確認してください。ok: false の場合は、error 文字列を読みます。
• メソッド名、スコープ、レートティア、引数は、最新のドキュメントページ（https://docs.slack.dev/reference/methods/<method-lowercased>.md）を参照してください。ドキュメントが信頼できる情報源です。最新の索引からメソッドを見つけ、各メソッド専用のページで仕様を確認してください。

禁止事項：

• メソッドが GET だと決めつけないでください。POST のものも多数あります。ドキュメントページを確認してください。
• コミットするコードにベアラートークンをハードコードしたり、平文で共有したりしないでください。
• 非推奨メソッド（files.upload、dialog.open、rtm.*、oauth.access、search.*、stars.*、reminders.*）は、置き換え先を確認せずに使用しないでください。非推奨メソッドのドキュメントページには、後継のメソッドが記載されています。新しいアプリでは置き換え先を優先してください。
• ページ番号を増やしてページネーションしないでください。Slack では不透明なカーソルを使用します（Step 5 を参照）。

実行方針 — 読み取りは実行し、書き込みは確認する：

• 読み取り専用メソッド（*.list、*.info、*.history、conversations.members、auth.test など）は、開発者を支援するために直接実行できます。
• 状態を変更するメソッドや破壊的なメソッド（chat.postMessage／update／delete、すべての *.delete／*.remove／*.kick／*.archive、およびすべての admin.*）は、正確なコマンドを用意し、実行前に開発者の確認を得てください。

---

クイックパス（明確で具体的なリクエストの場合）

開発者がすでにメソッドを把握している場合（メソッド名を指定した、https://slack.com/api/<method> の URL または docs.slack.dev/reference/methods/<method> のリンクを貼り付けた、あるいは family.method を指定した場合）は、探索を省略します。

1. メソッドの仕様を読むため、Step 2 に進みます。
2. 上記の実行方針に従って呼び出すため、Step 4 に進みます。

ワークフロー全体を開始するケース（Step 1 から始めます）：

• 「X にはどのメソッドを使いますか？」／「API 経由で…を一覧表示／取得／投稿するにはどうすればよいですか？」
• 目的の機能はわかっているものの、メソッド名がわからない場合。
• API でできることについての探索的な質問。

---

Step 1: メソッドを特定する（探索）

開発者の意図をファミリーに対応付け、次に候補のメソッドを特定します。

索引を参照する

最新のメソッド索引を WebFetch します。

https://docs.slack.dev/reference/methods.md

この索引には、すべての Web API メソッドが family.method 記法で一覧表示され、それぞれに 1 行の説明と専用のドキュメントページへのリンクが記載されています。完全で常に最新の内容です。候補を探し、メソッドのリンクをたどって Step 2 で仕様を確認してください（索引に記載されているのは説明のみです。レートティア、スコープ、トークン種別、ページネーションは各メソッドのページに記載されています）。

最新のページで確認していないメソッド名を公開したり、呼び出したりしないでください。

ドキュメントを検索する

索引を確認するよりキーワード検索を行いたく、Slack CLI が利用できる場合は、slack:slack-cli スキルの Step 3: ドキュメントを検索する（slack docs search） を使用し、ターミナルから Slack のドキュメントを検索します。このステップではコマンドとフラグについて説明しています。検索結果からメソッドのリファレンスページに移動し、Step 2 でそのページを読みます。CLI が利用できない場合は、WebFetch で索引（https://docs.slack.dev/reference/methods.md）を取得し、代わりに索引を確認してください。

---

ステップ 2：メソッドの仕様を読む（ナビゲート）

WebFetch でメソッドのドキュメントページを取得します。インデックス（ステップ 1）にあるメソッドのリンクをたどるか、URL を組み立てます。パスの部分はすべて小文字で、.md で終わります。

https://docs.slack.dev/reference/methods/<method-lowercased>.md

たとえば、conversations.members → https://docs.slack.dev/reference/methods/conversations.members.md、chat.postMessage → https://docs.slack.dev/reference/methods/chat.postmessage.md です。大文字・小文字が不確かな場合は、URL を手作業で組み立てず、インデックスのリンクをたどってください。

各メソッドのページには、以下の情報が一貫して記載されています。

• HTTP メソッド（GET / POST）とエンドポイント https://slack.com/api/<method>
• 必須の OAuth スコープとトークンの種類（ボット xoxb- とユーザー xoxp-）
• 引数 — 必須か任意か、および型
• リクエストとレスポンスの例
• エラーの表（メソッド固有のコード）
• レート制限のティア

呼び出す前に、必須の引数と必須スコープを確認してください。メソッドのページに記載された内容にとどまらない、これらの共通概念の一般的な意味については、レスポンスエンベロープ、POST ボディ、認証に関する正規のリファレンスが https://docs.slack.dev/apis/web-api.md にあります。ページネーションについては https://docs.slack.dev/apis/web-api/pagination.md、レート制限のティアについては https://docs.slack.dev/apis/web-api/rate-limits.md を参照してください。

---

ステップ 3：認証とスコープを確認する

公開されていないメソッドを呼び出すには、適切なスコープと種類のトークンが必要です。このスキルでは、ここでの目的は、ステップ 2 で読んだ仕様に基づき、メソッドが必要とするトークンの種類とスコープを特定することです。トークンを最終的にどのように送信するかは問いません。

ステップ 2 で読んだ仕様に基づいて、以下を確認します。

• トークンの種類を確認します。ボットトークンではユーザー専用メソッドを呼び出せず、その逆も同様です（メソッドのドキュメントページに、受け付けるトークンの種類が記載されています）。各トークンのプレフィックス（xoxb-、xoxp-、xapp-）の意味と使用方法については、https://docs.slack.dev/authentication/tokens.md を参照してください。
• 必須スコープを確認します。後で呼び出しが missing_scope で失敗した場合、レスポンスの needed フィールドと provided フィールドに不足しているスコープが示されます。アプリマニフェストに needed スコープを追加し、アプリを再インストールしてください。
• admin.* メソッドには、Enterprise Grid の組織レベルトークンが必要です。

認証が不要なメソッドもいくつかあります。api.test（接続確認）、auth.test（送信したトークンの有効性を検証）、および blocks.validate です。

トークンが必要なのは、メソッドが要求する場合のみです。トークンの取得方法は 2 つあります。開発者の環境に合った方法を選んでください。Slack CLI は任意です。開発者が Slack CLI を持っておらず、インストールも希望しない場合は、インストールを強制せずにパス B を選んでください。

パス A：Slack CLI を使う（インストール済み、または使用を希望する場合）

CLI は認証済みのセッションを提供するため、開発者のログイン後はトークンを自分で扱うことなくメソッドを呼び出せます（ステップ 4「Slack CLI 経由」）。

slack:slack-cli スキルのステップ 1：Slack CLI を検出するを使用して、公開されている Slack CLI がインストール済みか確認し、コマンド名を特定します。このステップでは、CLI が見つからない場合にインストールも提案します。フィンガープリントの確認、エイリアスへのフォールバック、インストール手順はすべてここに記載されています。ここで重複して説明しないでください。

コマンド名を特定したら、このスキルのすべての CLI コマンドで、検出されたコマンド名を使用してください。これを SLACK_CMD と表記します。SLACK_CMD が出てくる箇所はすべて、実際に特定したコマンド名に置き換えてください。

開発者のログイン状態を確認し、必要に応じて slack login の手順を案内するには、slack:slack-cli スキルの**ステップ 5：認証（slack auth）**を使用してください。認証の仕組みはすべてそこに記載されています。

パス B：CLI を使わない — トークンを自分で用意する

メソッドの呼び出しに CLI は必要ありません。Slack アプリの設定にある OAuth & Permissions ページ（https://api.slack.com/apps → 使用するアプリ → OAuth & Permissions → OAuth Tokens）から、上で確認した種類のトークンを取得します。Bot User OAuth Token（xoxb-…）または User OAuth Token（xoxp-…）を使用してください。このページには現在付与されているスコープも表示されるので、ステップ 2 で確認したスコープが含まれていることを確認します。その後、ステップ 4 の「生の HTTP 経由」または「SDK 経由」で、curl または SDK を使ってトークンを送信します。

---

ステップ 4：メソッドを呼び出す（管理）

まず、実行方針を適用します。メソッドが状態を変更する場合（投稿／更新／削除／アーカイブ／キック、または admin.*）、実行する前に開発者に正確なコマンドを提示し、実行してよいか確認します。読み取り専用の呼び出しは、そのまま実行できます。

Slack CLI 経由（インストール済みの場合）

ターミナルからメソッドを呼び出すには、slack:slack-cli スキルの **ステップ 4：Web API メソッドの呼び出し（slack api）**を使用します。このステップでは SLACK_CMD api <method> key=value … の構文を説明しているため、ここでは繰り返しません。ステップ 2 でメソッドのドキュメントページから確認した必須の引数を渡します。

CLI は開発者の認証済みセッションを使用するため、ログイン済みであれば最も簡単な方法です（ステップ 3）。

生の HTTP 経由（curl）

開発者が生のリクエストを希望する場合、または CLI を使用していない場合は、Bash ツールを使用します。ステップ 3 で取得したボットまたはユーザーのトークン（パス B、または CLI セッション）を Authorization ヘッダーに含めて送信します。

フォームエンコード（ほとんどのメソッドのデフォルト）：

curl -s -X POST 'https://slack.com/api/conversations.list' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'types=public_channel&limit=200'

JSON ボディ（blocks、view、attachments、metadata などの複雑な引数を取るメソッドの場合）：

curl -s -X POST 'https://slack.com/api/chat.postMessage' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"channel":"C0123456789","text":"Hello from the API"}'

メソッドのページで、必要なコンテンツタイプを確認してください。フォームエンコードの場合、構造化された引数は JSON でエンコードした文字列値として渡します（例：blocks=[...]）。

SDK 経由

Bolt と Slack SDK では、各メソッドはクライアント関数であり、引数はドキュメントページの引数表と一致します。

• JavaScript： await client.chat.postMessage({ channel, text, blocks })
• Python： client.chat_postMessage(channel=channel, text=text, blocks=blocks)

（JS のドット形式 chat.postMessage と Python のアンダースコア形式 chat_postMessage の違いに注意してください。）これらの呼び出しに渡す blocks／view ペイロードを構築するには、slack:block-kit スキルを使用します。このスキルではペイロードを不透明な引数として扱い、その周りのメソッド呼び出しに焦点を当てます。

---

ステップ 5：ページネーションを処理する

コレクションを返すメソッドでは、ページ番号ではなくカーソルページネーションを使用します。メソッドのドキュメントページにはページネーションの有無が記載されています。また、カーソルページネーションに対応するメソッドの一覧は https://docs.slack.dev/apis/web-api/pagination.md の カーソルベースのページネーションに対応するメソッド にあります。

1. limit（ページサイズ。メソッドの最大値を確認してください）を指定して呼び出します。
2. レスポンスから response_metadata.next_cursor を読み取ります。
3. 値が空でない場合は、cursor=<next_cursor> を指定して再度呼び出します。
4. next_cursor が空になるまで繰り返します。

# First page
curl -s -X POST 'https://slack.com/api/conversations.history' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'channel=C0123456789&limit=200'

# Next page — pass the cursor from response_metadata.next_cursor
curl -s -X POST 'https://slack.com/api/conversations.history' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='

カーソルは不透明です。古いカーソルを構築、解析、再利用しないでください。

---

ステップ 6：レート制限とエラーへの対処

ok が false の場合は、error の文字列に応じて分岐します。

• メソッド固有のコードについては、そのメソッドのドキュメントページ（ステップ 2）のエラー表を確認してください。not_authed、invalid_auth、missing_scope、channel_not_found、invalid_arguments など、複数のメソッドに共通するものも含め、そのメソッドが返すすべてのエラーが記載されています。
• エンベロープ自体（ok、error、warning、response_metadata）の意味については、https://docs.slack.dev/apis/web-api.md の Evaluating responses を参照してください。
• response_metadata.messages は、不正な引数の箇所を特定できることがよくあります。

レート制限： HTTP 429 または error: "ratelimited" が返された場合は、レスポンスヘッダーの Retry-After（秒数）に従ってください。待機してから再試行します。短い間隔で繰り返し再試行しないでください。各メソッドにはティア（1～4 または特別）があり、1 分あたりの呼び出し回数に上限があります。ティアの表は https://docs.slack.dev/apis/web-api/rate-limits.md にあります。また、新しい非 Marketplace アプリでは一部のメソッドにより厳しい上限が適用されるため、正確な回数は各メソッドのページを確認してください。

---

備考

• Slack Lists のメソッドには slackLists.* プレフィックスを使用します。lists.* という名前のメソッドは存在しません。
• スコープ： このスキルが担当するのはメソッド層、つまりメソッド、そのコントラクト、およびその呼び出しです。CLI 認証と呼び出しは slack:slack-cli に、Block Kit ペイロードは slack:block-kit に委任します。