結論

Slack API で通知を送るだけなら Incoming Webhook(URL に JSON を POST)、送り先を選んだり返事をしたりするなら Web API の chat.postMessage、会話に反応する Bot なら Bolt for Python と Socket Mode を使います。トークンはコードに書かず環境変数に置きます。

この記事でわかること

  • Web API・Events API・Incoming Webhook・Socket Mode の違いと選び方
  • slack_sdk・Bolt を模擬サーバーに向けて動かした送信内容とエラーの原文
  • 3秒ルール・429 の待ち方・署名検証を実測した結果

2026年11月18日更新|slack_sdk 3.47.0・slack_bolt 1.30.0・Python 3.13 で実行確認(Slack には接続せず 127.0.0.1 の模擬サーバーで確認)

この記事で実際に動かしたもの:slack_sdk と slack_bolt を入れた Python の仮想環境と、127.0.0.1 で動かした自作の模擬サーバー(Web API・Incoming Webhook・Socket Mode の WebSocket)です。本物の Slack には接続していません。

Slack API は、プログラムから Slack に「送る」道と、Slack から出来事を「受け取る」道に分かれます。図のどちらの向きかで、使う仕組みが決まります。

flowchart TD
    P[自分のプログラム] -->|Incoming Webhook<br>URL に JSON を POST| S[Slack]
    P -->|Web API<br>chat.postMessage など| S
    S -->|Events API<br>公開 URL に POST| H[サーバー上のアプリ]
    S -->|Socket Mode<br>WebSocket| W[社内 PC のアプリ]

よく調べられることの答えを先にまとめます。

知りたいこと 答え 詳しい節
Slack API とは Slack をプログラムから操作する仕組みの総称。Web API・Events API など Slack API とは
Slack Webhook の使い方 アプリで Incoming Webhooks を有効にし、発行された URL に JSON を POST Incoming Webhook で送る
Python でメッセージ送信 slack_sdk の WebClient で chat_postMessage を呼ぶ chat.postMessage を使う
Slack Bot の作り方 Bolt for Python で @app.message を書き、Socket Mode で起動 Bolt で Bot を作る
トークンの種類 xoxb-(Bot)・xoxp-(ユーザー)・xapp-(アプリレベル) トークンの種類と置き場所
not_in_channel が出る Bot をチャンネルに招待するか chat:write.public を付ける エラー一覧
レート制限 投稿は1チャンネルにおおむね1秒1件。429 なら Retry-After 秒待つ レート制限の扱い
無料で使えるか フリープランでもアプリを入れられる(10個まで) よくある質問

確認環境:Ubuntu 24.04.5 LTS の上で、Python 3.13.18 の仮想環境に slack_sdk 3.47.0・slack_bolt 1.30.0・aiohttp 3.14.5 を pip で入れて動かしました。送り先は、標準ライブラリの http.server と aiohttp で作った自作の模擬サーバー(127.0.0.1。Web API の chat.postMessage・auth.test・conversations.history・apps.connections.open、Incoming Webhook の URL、Socket Mode の WebSocket の役)で、Slack のサーバーには一度も接続していません。Slack へのログイン・アプリの作成・トークンの発行もしていません。そのため、模擬サーバーが返すエラーの文字列は公式ドキュメントのエラー一覧から選んだもので、本物の Slack の応答そのものではありません(SDK が送る内容と、エラーを受けたときの SDK の動きは本物です)。curl は 8.5.0 です。アプリの作成・スコープ・インストールの画面の名前、レート制限、トークンの種類、Events API の再送の決まりは、Slack の開発者向けドキュメント(docs.slack.dev)とヘルプセンターで確かめました。図は mermaid で描画を確かめています(確認日 2026年11月18日)。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「Slack APIの使い方|Pythonで送信・Bot作成・Webhookの始め方」

Slack API とは(4つの種類と違い)

この節では、Slack API と呼ばれるものの中身と、Web API・Events API・Incoming Webhook・Socket Mode の役割の違いが分かります。

Slack API は、Slack の投稿・チャンネル・ユーザーなどをプログラムから扱うための仕組みの総称です。 公式ドキュメントは、Web API を「Slack アプリの機能の大半を支える HTTP のメソッドの集まり」、Events API を「Slack の中の出来事に反応するアプリを作るための仕組み」と説明しています。

1Incoming Webhook(送るだけ)

アプリに発行された URL に JSON を POST すると、決まったチャンネルに投稿されます。トークンは要りませんが、URL そのものが秘密の鍵です。

2Web API(操作する)

https://slack.com/api/メソッド名 を呼ぶ形。chat.postMessage(投稿)・conversations.history(履歴)・users.info(ユーザー)など。トークンが要ります。

3Events API(受け取る)

「メッセージが投稿された」「メンションされた」などの出来事を、Slack がアプリの公開 URL に POST で知らせます。

4Socket Mode(受け取る・公開 URL なし)

Events API と対話の機能を、WebSocket の接続で受け取ります。公開の HTTP の URL を用意できない環境向けです。

このほか、組織の管理向けの Admin API・SCIM API・Audit Logs API があり、以前の RTM API は非推奨(deprecated)と書かれています。ここでは、通知と Bot で使う4つを扱います。

種類 向き 必要なもの 向いている用途
Incoming Webhook 送る Webhook の URL CI・バッチ・監視の通知を1つのチャンネルへ
Web API 送る・読む・変える Bot トークン(xoxb-)とスコープ 送り先を選ぶ・スレッドに返信・更新や削除
Events API 受け取る 公開 URL・Signing Secret サーバーで動かす Bot・問い合わせの自動応答
Socket Mode 受け取る アプリレベルトークン(xapp-) 社内ネットワーク内の Bot・開発中の試し

Webhook そのものの考え方(署名・リトライ・冪等性)は、関連記事「Webhookとは?実装までわかる|署名検証・リトライ・冪等性を実行ログで解説」で扱っています。

Slack アプリの作成とスコープ(権限)の付け方

この節では、Slack API を使う入口になる「Slack アプリ」の作り方と、スコープの考え方が分かります。

Slack API は、まず Slack アプリを作り、必要なスコープ(権限)を付けてワークスペースにインストールすると使えるようになります。 次の手順と画面の名前は、Slack の開発者向けドキュメントのクイックスタートの記載です(この記事の作業ではアプリを作っていません)。

1

アプリを作る

Slack のアプリ管理の画面で「Create New App」を選び、ドキュメントの例では「Pick features」→「Continue」と進みます。「App Name」を入れ、開発に使う「Workspace」を選んで「Create」で作ります。

アプリ管理の画面(ブラウザ)

2

スコープを足す

「OAuth & Permissions」の「Scopes」にある「Bot Token Scopes」で「Add an OAuth Scope」を選び、投稿に使う chat:write などを足します。

必要な分だけ付ける

3

ワークスペースに入れる

「OAuth & Permissions」の上にある「Install to Workspace」を選び、次の画面で「Allow」を選びます。

管理者の承認が要る組織もある

4

トークンを控える

インストール後、「OAuth & Permissions」の「OAuth Tokens」にアクセストークンが表示されます。Bot トークンは xoxb- で始まります。

環境変数に置く(次の節以降)

よく使うスコープを、公式のメソッドのページの記載から並べます。メソッドのページには、そのメソッドに必要なスコープが必ず書かれているので、足りないときはそこを見ます。

スコープ できること 使うメソッドの例
chat:write アプリが参加しているチャンネルに投稿 chat.postMessage
chat:write.public 参加していない公開チャンネルにも投稿(chat:write も必要) chat.postMessage
channels:read 公開チャンネルの情報を読む conversations.list など
channels:history ほか 履歴を読む(非公開は groups:history、DM は im:history) conversations.history
connections:write アプリレベルトークンで Socket Mode の接続を開く apps.connections.open

スコープは後から足せますが、足したら再インストール(もう一度「Allow」)が要ります。足りないまま呼ぶと missing_scope になります(エラー一覧の節)。

Incoming Webhook でメッセージを送る(いちばん手早い方法)

この節では、Slack Webhook の作り方と、curl と Python で送った結果、送れないときのエラーの原文が分かります。

Incoming Webhook は、アプリの「Incoming Webhooks」で「Activate Incoming Webhooks」をオンにし、「Add New Webhook to Workspace」でチャンネルを選んで「Authorize」すると URL が発行されます。 発行された URL は「Webhook URLs for Your Workspace」に並びます。公式ドキュメントは「Webhook の URL には秘密が含まれる。ネット上で共有しない」と注意しています。

URL の形は https://hooks.slack.com/services/T…/B…/… です。そこに Content-type: application/json で text を含む JSON を送ります。模擬サーバーに向けて curl で送った結果です(URL は公式ドキュメントの見本の形で、ホストだけ 127.0.0.1 に置き換えています)。

curl -i -X POST -H 'Content-type: application/json' \
  --data '{"text":"夜間バッチが終了しました"}' \
  http://127.0.0.1:18616/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
HTTP/1.0 200 OK
Content-Type: text/html
Content-Length: 2

ok

成功すると、JSON ではなく ok の2文字が返る形です(模擬サーバーはこの形に合わせています)。Python では slack_sdk の WebhookClient を使うと、JSON の組み立てと送信を任せられます。

import os
from slack_sdk import WebhookClient

webhook = WebhookClient(os.environ["SLACK_WEBHOOK_URL"])
r = webhook.send(text="夜間バッチが終了しました")
print(r.status_code, repr(r.body))
200 'ok'

失敗したときは、HTTP のステータスと短いエラーの文字列が返ります。公式ドキュメントのエラー一覧のうち、手元で起こした3つの結果です。

URL の最後を書き換えた       -> 404 'no_service'
text も blocks も無い JSON   -> 400 'no_text'
改行を生のまま入れた壊れた JSON -> 400 invalid_payload

3つめは、文字列の中に改行をそのまま入れて JSON として正しくない形にしたものです。json.dumps で作れば、改行は \n に置き換わります。

エラー 公式の説明(要約) 直し方
invalid_payload JSON が正しくない・エスケープの誤り json.dumps で作る。手書きの JSON をやめる
no_text text が無い blocks を送るときも text を入れる
no_service Webhook が無効・削除済み・URL の誤り URL を貼り直す。消えていれば作り直す
channel_is_archived チャンネルがアーカイブされている 別のチャンネルで Webhook を作り直す
action_prohibited 管理者が投稿を制限している ワークスペースの管理者に確かめる
too_many_attachments 添付(attachments)が100を超えた 分けて送る

Incoming Webhook には、公式に書かれた制約があります。 チャンネル・表示名・アイコンは上書きできず、アプリの設定を引き継ぎます。送った投稿を後から消せず、スレッドに返信するための ts(投稿の時刻 ID)も返りません。これらが要るなら、次の節の chat.postMessage を使います。Google Apps Script から Webhook で送る書き方は「GASでSlack・Google Chatに通知|Webhookの書き方」にまとめています。

Python で chat.postMessage を使う(slack_sdk の実行結果)

この節では、Python の公式 SDK(slack_sdk)でメッセージを送る書き方と、SDK が実際に送っている中身が分かります。

slack_sdk の WebClient にトークンを渡し、chat_postMessage(channel=..., text=...) を呼ぶと投稿できます。 公式ドキュメントの例も、トークンを環境変数 SLACK_BOT_TOKEN から読んでいます。slack_sdk と slack_bolt の配布情報(METADATA)では、必要な Python は 3.7 以上でした。

python3 -m venv .venv
. .venv/bin/activate
pip install slack_sdk slack_bolt
export SLACK_BOT_TOKEN='xoxb-...'   # 実際の値はシェルの履歴に残らない方法で設定する

仮想環境の作り方は、関連記事「Python venvの使い方|作成・有効化コマンド早見表と有効化できない時の直し方」で扱っています。

import os
from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError

# base_url は検証のため模擬サーバーへ向けた。本番では指定しない(https://slack.com/api/ になる)
client = WebClient(token=os.environ["SLACK_BOT_TOKEN"], base_url="http://127.0.0.1:18616/api/")

print(client.auth_test().data)          # トークンが通るかの確認
r = client.chat_postMessage(channel="C0TEST0001", text="ビルドが完了しました")
print(r.status_code, r["ok"], r["channel"], r["ts"])
{'ok': True, 'url': 'https://example.slack.com/', 'team': 'Example', 'user': 'testbot', 'team_id': 'T00000000', 'user_id': 'U0BOT00001', 'bot_id': 'B0BOT00001'}
200 True C0TEST0001 1794962455.047169

模擬サーバーの側で、届いたリクエストを記録しました。SDK は、トークンを Authorization: Bearer のヘッダーに入れ、本文を JSON で送っています。公式ドキュメントにも「JSON で送るときは Content-type を application/json にし、トークンは JSON の中やクエリ文字列に入れず Authorization ヘッダーで送る」とあり、その形どおりです。

POST /api/chat.postMessage
Content-Type: application/json;charset=utf-8
Authorization: Bearer xoxb-test…
User-Agent: Python/3.13.18 slackclient/3.47.0 Linux/6.18.44-fc-v595
{"channel": "C0TEST0001", "text": "ビルドが完了しました"}

日本語は \uXXXX の形に置き換えて送られていますが、JSON としては同じ文字列です。成功の応答には channel(チャンネル ID)と ts が入ります。この ts を thread_ts に渡すとスレッドに返信でき、chat.update・chat.delete で更新や削除もできます。 ここが Incoming Webhook との大きな違いです。

失敗すると SlackApiError になる

Web API は、応答の JSON の ok が false のとき、error に短いエラーコードを入れて返します。slack_sdk はそれを SlackApiError という例外にします。手元で起こした結果です。

for ch in ["C0OTHER001", "general"]:
    try:
        client.chat_postMessage(channel=ch, text="test")
    except SlackApiError as e:
        print(ch, "->", e.response.status_code, e.response["error"])
        print(str(e).splitlines()[0])
C0OTHER001 -> 200 not_in_channel
The request to the Slack API failed. (url: http://127.0.0.1:18616/api/chat.postMessage)
general -> 200 channel_not_found
The request to the Slack API failed. (url: http://127.0.0.1:18616/api/chat.postMessage)

例外のメッセージの1行目は「The request to the Slack API failed.」だけなので、原因は e.response["error"] を必ずログに出して見ます。 同じ方法で、トークンを間違えたときは invalid_auth、トークンを渡さなかったときは not_authed、スコープが足りないメソッドを呼んだときは missing_scope を受け取れることを確かめました。

チャンネルは名前ではなく C で始まるチャンネル ID で指定するほうが確実です。ID は、Slack のチャンネルの詳細の画面や、conversations.list の結果で確かめられます。

Block Kit で見やすいメッセージにする

この節では、見出し・項目・区切り線のある通知を Block Kit で作る書き方と、ブロックの数の上限が分かります。

Block Kit は、メッセージを「ブロック」の JSON の配列で組み立てる仕組みです。 公式ドキュメントには、1つのメッセージに入れられるブロックは50個まで(モーダルとホームタブは100個まで)と書かれています。ブロックの種類には header・section・divider・context・actions・image などがあります。

blocks = [
    {"type": "header", "text": {"type": "plain_text", "text": "デプロイ通知"}},
    {"type": "section", "fields": [
        {"type": "mrkdwn", "text": "*環境*\nstaging"},
        {"type": "mrkdwn", "text": "*版*\nv1.4.2"}]},
    {"type": "divider"},
    {"type": "context", "elements": [{"type": "mrkdwn", "text": "2026-11-18 10:00 JST"}]},
]
r = client.chat_postMessage(channel="C0TEST0001", text="デプロイ通知(staging v1.4.2)", blocks=blocks)
print(r["ok"])
r = webhook.send(text="デプロイ通知", blocks=blocks)   # Incoming Webhook でも同じ blocks を送れる
print(r.status_code, repr(r.body))
True
200 'ok'

blocks を送るときも text を入れます。 text は通知(プッシュ通知やデスクトップ通知)に出る文になり、Webhook では text も blocks も無いと no_text になります。模擬サーバーには「51個以上のブロックは invalid_blocks を返す」決まりを入れ、divider を51個並べて送ると invalid_blocks の SlackApiError になることも確かめました(本物の Slack が返すエラー名は、chat.postMessage のエラー一覧で確かめてから扱います)。

ブロック 使いどころ 書き方の要点
header 通知の見出し text は plain_text だけ
section 本文・項目の並び fields で2列の表のように並べられる
divider 区切り線 type だけ
context 時刻・補足の小さな文字 elements に mrkdwn や image
actions ボタン・選択肢 押されたことを受け取るには Bot の仕組みが要る

ブロックの組み立ては、公式の Block Kit Builder で見た目を確かめながら作れます。chat.postMessage の text は4,000字までに収めるよう公式に書かれており、40,000字を超えると切り詰められます。

Bolt for Python で Slack Bot を作る(Socket Mode)

この節では、話しかけると返事をする Bot を Bolt for Python で作る手順と、Socket Mode で実際に流れたやりとりが分かります。

Bolt for Python は、Slack が出している Bot づくりのためのフレームワークです。 公式のチュートリアルの最小のコードは次のとおりで、「hello」を含むメッセージに返事をします。

import os
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

app = App(token=os.environ.get("SLACK_BOT_TOKEN"))

@app.message("hello")
def message_hello(message, say):
    say(f"Hey there <@{message['user']}>!")

if __name__ == "__main__":
    SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start()

Slack 側の設定は、公式のチュートリアルでは次の順です。

  1. 1Bot のスコープに chat:write を足す「OAuth & Permissions」で。Bot トークン(xoxb-)を SLACK_BOT_TOKEN に
  2. 2アプリレベルトークンを作る「Basic Information」の「App-Level Tokens」で「Generate Token and Scopes」。connections:write を付け、xapp- を SLACK_APP_TOKEN に
  3. 3Socket Mode をオンにする左のメニューの「Socket Mode」で切り替える
  4. 4受け取る出来事を選ぶ「Event Subscriptions」で「Enable Events」をオン。「Subscribe to Bot Events」に message.channels などを足して「Save Changes」

message.channels は公開チャンネル、message.groups は非公開チャンネル、message.im は Bot との DM、message.mpim は複数人の DM のメッセージです。

Socket Mode で流れたやりとり(模擬サーバー)

このコードを、トークンの読み込みはそのままに、WebClient の送り先だけ 127.0.0.1 の模擬サーバーに向けて起動しました。模擬サーバーは接続してきた Bot に「hello」というメッセージの出来事を1件送ります。記録はこうなりました。

HTTP auth.test Bearer xoxb-
HTTP apps.connections.open Bearer xapp-
WS sent envelope
WS recv 83.6ms {"envelope_id": "57d6a792-4d35-4997-a295-ca8e6d4a1e6a"}
HTTP chat.postMessage Bearer xoxb- {"channel": "C0TEST0001", "text": "Hey there <@U0USER0001>!", "team_id": "T00000000"}

順に読むと、Bolt は起動時に Bot トークンで auth.test を呼び、アプリレベルトークン(xapp-)で apps.connections.open を呼んで WebSocket の URL を受け取り、そこに接続しています。出来事を受け取ると、受け取ったしるしとして envelope_id だけの JSON を送り返し(ここでは83.6ミリ秒後)、そのあと Bot トークンで chat.postMessage を呼んで返事をしています。公式ドキュメントにも、Socket Mode でも出来事ごとに envelope_id を返して受け取りを知らせる必要があると書かれています。

Socket Mode には公式に書かれた条件があります。同時に開ける WebSocket の接続は10本までで、Socket Mode を使うアプリは今のところ公開の Slack Marketplace に載せられません。社内で使う Bot や、開発中の試しに向いています。

HTTP モードと Events API の3秒ルール(実測)

この節では、公開 URL で出来事を受け取る HTTP モードの動かし方と、「3秒以内に返す」決まりを Bolt がどう守っているかが分かります。

Socket Mode

公開 URL が要らない。社内のファイアウォールの内側でも動く

アプリレベルトークン(xapp-)が要る

届いた出来事の署名の検証は不要(公式の説明)

公開の Marketplace には載せられない

HTTP モード(Events API の Request URL)

Slack から届く HTTPS の公開 URL が要る

Signing Secret でリクエストの署名を検証する

3秒以内に 2xx を返す。返せないと再送される

サーバーを複数台に増やしやすい

公式ドキュメントによると、Events API の出来事には3秒以内に HTTP 2xx で応える必要があり、遅れたり失敗したりすると最大3回まで再送されます(1回目はほぼすぐ、2回目は1分後、3回目は5分後)。再送の回数は x-slack-retry-num、理由は x-slack-retry-reason のヘッダーで分かります。60分の間に配信の95%を超えて失敗すると、出来事の配信が一時的に止められます(1時間の出来事が1,000件未満のアプリは自動では止められません)。

Bolt を HTTP モードで動かすには、signing_secret を渡して app.start(port=...) で起動します。Bolt 1.30.0 のソースでは、受け口の既定のパスは /slack/events でした。署名をつけた出来事を自分で送ってみた結果です。

url_verification: (200, '{"challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"}', 23.6)
message hello:    (200, '', 3.7)
app_mention:      (200, '', 2.2)
bad signature:    (401, '{"error": "invalid request"}', 1.3)
old timestamp:    (401, '{"error": "invalid request"}', 0.5)

かっこの中は(HTTP ステータス、応答の本文、かかったミリ秒)です。Request URL を登録するときに届く url_verification には、Bolt が challenge の値を返しています。署名を壊したものと、10分前の時刻をつけたものは 401 で断られました。

重い処理があっても3秒を超えない仕組み

返事の前に4秒かかる処理(time.sleep(4))を入れて、応答までの時間を測りました。

Bolt の設定 HTTP 200 が返るまで Slack から見ると
既定(process_before_response=False) 21.8 ミリ秒 先に 200 を返し、処理は後ろで続く。再送されない
process_before_response=True 4,022.8 ミリ秒 3秒を超えるので失敗の扱いになり、再送される

既定の設定では、Bolt が先に受け取りの応答を返し、聞き手の関数(リスナー)は別に動きます。process_before_response=True は、処理が終わるまで応答を返さない設定なので、重い処理を入れるなら既定のままにするか、処理を別の仕組み(キューなど)に渡します。 再送が来ても二重に投稿しないよう、event_id で処理済みかを確かめる作りにしておくと安心です。

手元の PC で HTTP モードを試すときは、外から届く URL が要ります。その方法は関連記事「ngrokとは|使い方・料金・Webhook受信とエラーの直し方」で扱っています。公開 URL を用意しないなら Socket Mode が手早い方法です。

リクエストの署名を検証する(公式の例を再計算)

この節では、Slack から届いたリクエストが本物かを確かめる署名の計算方法と、公式の例と同じ値になるかの確認結果が分かります。

Slack は、HTTP で送るリクエストに X-Slack-Signature と X-Slack-Request-Timestamp のヘッダーをつけます。 受け取る側は、v0:時刻:本文 をつないだ文字列を Signing Secret を鍵にして HMAC-SHA256 で計算し、先頭に v0= をつけた値がヘッダーと一致するかを比べます。公式ドキュメントは、時刻が手元の時計と5分を超えてずれていたら断ることも勧めています。

import hmac, hashlib
from slack_sdk.signature import SignatureVerifier

secret = "8f742231b10e8888abcd99yyyzzz85a5"   # 公式ドキュメントの例の値
ts = "1531420618"
body = "token=xyzz0WbapA4vBCDEFasx0q6G&team_id=T1DC2JH3J&...(公式の例の本文の全文)"
sig = "v0=" + hmac.new(secret.encode(), f"v0:{ts}:{body}".encode(), hashlib.sha256).hexdigest()
print(sig)
v0=a2114d57b48eac39b9ad189dd8316235a7b4a8d21a10bd27519666489c69b503
True   ← 公式ドキュメントに載っている署名と一致

slack_sdk の SignatureVerifier でも、同じ例を時計をずらして確かめました。

条件 is_valid の結果 理由
例の時刻から10秒後 True 署名が一致し、5分以内
例の時刻から301秒後 False 5分(300秒)を超えた
本文を1文字変えた(10秒後) False 署名が一致しない
今の時刻(2018年の例をそのまま) False 時刻が古すぎる

比べるときは == ではなく hmac.compare_digest のような比較用の関数を使うよう、公式に書かれています。Bolt は signing_secret を渡せばこの検証を自動で行い、前の節のとおり不正なものは 401 で断ります。本文は、受け取った生のバイト列のまま計算します(JSON を読み込んで作り直すと一致しません)。

Slack API のレート制限(429 と Retry-After)の扱い

この節では、Slack API の呼び出し回数の上限と、上限に当たったときの待ち方を slack_sdk で動かした結果が分かります。

Web API のメソッドには、ワークスペースごと・メソッドごとに1分あたりの上限(Tier)があります。 上限を超えると HTTP 429 Too Many Requests が返り、Retry-After のヘッダーに待つ秒数が入ります。Incoming Webhook も同じく 429 になります。

1件/秒1チャンネルへの投稿chat.postMessage・Webhook とも。短い連続は許される
50+回/分Tier 3 の目安conversations.history・apps.connections.open など
数百件/分ワークスペース全体の投稿chat.postMessage のページの記載
Tier 1分あたり 1回あたりの間隔(計算) 1,000回呼ぶのにかかる時間(計算)
Tier 1 1+ 60.0 秒 約1,000分
Tier 2 20+ 3.0 秒 約50分
Tier 3 50+ 1.2 秒 約20分
Tier 4 100+ 0.6 秒 約10分

「+」は、それ以上を許すこともあるという意味の公式の表記で、表の右2列は最低の値から計算した目安です。投稿は特別な扱いで、1チャンネルにおおむね1秒1件です。300件の通知を1チャンネルに送ると約300秒(5分)かかり、1件ずつ待たずに送ると 429 が続きます。まとめられる通知は1件にまとめるのが近道です。

2025年5月29日の変更:Slack Marketplace の承認を受けずに外部へ配布するアプリでは、conversations.history と conversations.replies が1分に1回・1回15件までになりました。社内で作って使うアプリ(internal customer-built)はこの変更の対象外で、50回/分以上の上限のままと書かれています(2026年11月18日時点の公式の記載)。

RateLimitErrorRetryHandler で自動で待つ

slack_sdk は、既定では接続のエラーだけを再試行します。429 で自動的に待たせるには、公式が案内している RateLimitErrorRetryHandler を足します。模擬サーバーを「3回に2回は 429、Retry-After: 2」にして測りました。

from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler
client.retry_handlers.append(RateLimitErrorRetryHandler(max_retry_count=2))
ハンドラーなし            : SlackApiError 429 ratelimited(Retry-After= 2)をすぐ受け取る
max_retry_count=2 : ok=True / 4.95s   (429 → 待つ → 429 → 待つ → 成功)
max_retry_count=1 : SlackApiError 429 ratelimited / 2.63s

slack_sdk 3.47.0 のソースを読むと、待つ時間は「Retry-After の秒数+0〜1秒の乱数」でした。2秒の指定で1回待つと約2.6秒、2回待つと約5秒になり、測った値と合います。再試行の回数を使い切ると例外になるので、呼び出す側でも SlackApiError を受け止めてログに残します。 HTTP の再試行の一般的な書き方は、関連記事「Pythonのrequestsの使い方|タイムアウト・エラー処理・再試行まで」で扱っています。

トークンの種類と安全な置き場所

この節では、Slack のトークンの見分け方と、コードに書かずに使う方法、漏れたときの対応が分かります。

種類 先頭 何を表すか(公式の説明) 主な使いどころ
Bot トークン xoxb- ワークスペースに入れたアプリの Bot 投稿・Bot の操作(いちばんよく使う)
ユーザートークン xoxp- ワークスペースのメンバー本人 本人として操作する。書き込みは本人の操作になる
アプリレベルトークン xapp- 組織をまたいだアプリそのもの Socket Mode の接続
ローテーションするアプリレベルトークン xoxe.xapp- 12時間で切れ、更新用トークンで作り直す ローテーションを有効にしたアプリ
Signing Secret (トークンではない) Slack からのリクエストの署名の鍵 HTTP モードの受け口の検証

このほか、ワークフローのトークン(xwfp-)や、アプリを設定するための構成トークンもあります。公式のセキュリティのガイドは、秘密の値をソースコードに直接書かない、開発中は環境変数(.env)に置き、.env を .gitignore に入れてコミットしないことを勧めています。トークンが漏れたら、すぐに無効にして作り直します(公式は auth.revoke メソッドで無効にできると案内しています)。

トークンの置き場所

やってはいけないTOKEN = "xoxb-…" とコードに書く・Webhook の URL を README やチャットに貼る
↔
代わりにos.environ["SLACK_BOT_TOKEN"] で読む。.env は .gitignore に入れ、本番は秘密の値を保管する仕組みに置く

見分ける問い:「このファイルを公開しても、Slack に投稿できる人は増えないか」

手元では、コミットの前にトークンらしき文字列が無いかを調べる小さなスクリプトを動かしました。直書きしたファイルだけが引っかかります。環境変数を設定し忘れて起動すると、KeyError: 'SLACK_BOT_TOKEN' ですぐ止まるので、設定漏れにも気づけます。

import re, pathlib, sys
PAT = re.compile(r"\b(xox[abpe]|xapp)-[0-9A-Za-z-]{8,}|hooks\.slack\.com/services/\S+")
for p in sorted(pathlib.Path(sys.argv[1]).rglob("*.py")):
    for i, line in enumerate(p.read_text().splitlines(), 1):
        if PAT.search(line):
            print(f"{p.name}:{i}: トークンらしき文字列 -> {PAT.search(line).group(0)[:9]}...")
bad.py:2: トークンらしき文字列 -> xoxb-1234...

公式のガイドには、アプリの OAuth トークンを使える IP アドレスを最大20件まで登録して絞る方法もあります(IPv6 は対象外、Incoming Webhook には効かない)。Slack アプリのインストールで使われる OAuth の考え方は、関連記事「OAuth 2.0とOpenID Connectの違いをわかりやすく解説」で扱っています。

Slack API のエラー一覧(原文と直し方)

この節では、Slack API でよく出るエラーコードの意味と、まず確かめることが分かります。

Web API のエラーは、応答の error に入る短い英語のコードで見分けます。 意味は chat.postMessage などの各メソッドのページのエラー一覧の記載です。「手元」の列は、模擬サーバーで起こして slack_sdk の動きを確かめたものです。

エラーの原文 意味(公式の説明) まず確かめること 手元
not_in_channel 参加していないチャンネルには投稿できない Bot をチャンネルに招待する。公開チャンネルなら chat:write.public 再現
channel_not_found channel の値が正しくない 名前ではなくチャンネル ID(C…)で指定する 再現
missing_scope トークンに必要なスコープが無い メソッドのページのスコープを足し、再インストール 再現
invalid_auth 認証を確かめられない(トークンが無効・許可されていない IP など) トークンの貼り間違い・別のワークスペースのトークン 再現
not_authed トークンが渡されていない 環境変数が空・Authorization ヘッダーが無い 再現
ratelimited 上限に当たった。Retry-After を見る RateLimitErrorRetryHandler・送る間隔 再現
no_text メッセージの文が無い text を入れる(blocks だけにしない) 再現
is_archived チャンネルがアーカイブされている 送り先のチャンネルを変える 公式のみ
msg_blocks_too_long blocks が長すぎる ブロックの数・文字数を減らす 公式のみ

Socket Mode の接続で使う apps.connections.open では、アプリレベルトークン以外を渡したときの not_allowed_token_type、トークンが無いときの missing_args などが一覧に載っています。Bot トークン(xoxb-)を SLACK_APP_TOKEN に入れてしまう取り違えが典型です。

Slack API がうまくいかないときの症状表

この節では、エラーコードが出ない場合も含め、症状から原因と直し方を引けます。

症状 よくある原因 確かめ方 直し方
Webhook が 404 no_service URL の誤り・Webhook が消された 「Webhook URLs for Your Workspace」に残っているか URL を貼り直す・作り直す
Webhook が 400 invalid_payload JSON の手書き・改行や引用符のエスケープ漏れ 送る文字列を json.loads で読めるか json.dumps で作る
投稿が届かず not_in_channel Bot がチャンネルにいない チャンネルのメンバーにアプリがいるか アプリを招待する
スコープを足したのに missing_scope 再インストールしていない 「OAuth & Permissions」の表示 「Install to Workspace」をやり直す
Bot が反応しない 出来事を購読していない・Socket Mode がオフ 「Event Subscriptions」の Bot Events の一覧 message.channels などを足して保存
同じ返事が2〜4回届く 3秒以内に応答できず再送された x-slack-retry-num のヘッダー 先に応答する・event_id で重複を除く
HTTP モードで 401 が返る Signing Secret の誤り・サーバーの時計のずれ 時刻の差が5分以内か Signing Secret を貼り直す・時刻を合わせる
blocks だけ送ると通知が空 text を入れていない 送った JSON に text があるか text に要約を入れる

Webhook・chat.postMessage・Bolt のどれを使うか(判断表)

この節では、やりたいことから使う仕組みを1つに決められます。

やりたいこと 選ぶもの 理由
CI・バッチの結果を決まったチャンネルに出す Incoming Webhook URL だけで送れる。トークンもスコープも要らない
送り先を条件で変える・スレッドに続ける chat.postMessage channel を毎回選べ、ts で返信・更新・削除できる
投稿の後で内容を書き換える(進み具合の表示) chat.postMessage + chat.update Webhook は投稿を後から変えられない
話しかけたら返事をする Bot(社内) Bolt + Socket Mode 公開 URL が要らず、手元の PC でも動く
多くのワークスペースに配る Bot Bolt + HTTP モード Socket Mode のアプリは公開の Marketplace に載せられない
Slack から届く出来事を本物か確かめたい HTTP モード + Signing Secret Bolt に signing_secret を渡せば署名と時刻を自動で確かめる

公開する前に、次の4つを確かめておくと、つまずきが減ります。

  • 1トークン・Webhook の URL・Signing Secret がコードに無い環境変数か秘密の値を保管する仕組みから読む
  • 2スコープは使うメソッドの分だけ足したら再インストール
  • 3SlackApiError の e.response["error"] をログに残す例外の1行目だけでは原因が分からない
  • 4429 と再送への備えがあるRateLimitErrorRetryHandler と event_id による重複の除去

ほかのチャットツールの Bot と比べたいときは、未公開の記事「Discord Botの作り方|Pythonで作る手順・トークンとスラッシュコマンド」でも同じ流れ(トークン・イベント・返事)を扱っています。Slack の絵文字の使い方は「Slackの絵文字・スタンプの使い方|カスタム絵文字の作り方と決まりの例」で扱っています。

Slack API の使い方に関するよくある質問

この節では、Slack API を使い始めるときによく出る疑問への答えが分かります。

Q. Slack API は無料で使えますか?
フリープランのワークスペースでもアプリを入れて使えます。ヘルプセンターには、フリープランではサードパーティ製アプリとカスタムアプリのインストールが10個までと書かれています(2026年11月18日時点)。メッセージの履歴が直近90日分に限られる点も、履歴を読む使い方では関わります。

Q. Webhook と chat.postMessage はどちらがよいですか?
決まったチャンネルに通知を出すだけなら Webhook が手早い方法です。送り先を選ぶ、スレッドに返信する、後から更新・削除するなら chat.postMessage を使います。

Q. Python 以外でも使えますか?
Web API と Webhook は HTTP なので、curl や任意の言語から呼べます。Slack は Python のほかに JavaScript・Java 向けの Bolt と SDK も出しています。

Q. Bot が自分の投稿に反応して止まらなくなりませんか?
Bolt には、自分自身が出した出来事を無視する設定(ignoring_self_events_enabled)があり、1.30.0 では既定でオンでした。手元で、Bot 自身の ID(bot_id)がついた「hello」を送ると返事は0件、ほかの人の「hello」には1件返すことを確かめました。この設定を切ると、返事の文に反応する語が入っていたときに繰り返しが起こりえます。

Q. チャンネル ID はどこで分かりますか?
Slack のチャンネルの詳細の画面に表示されるほか、conversations.list の結果にも入っています。C で始まる文字列です。

Q. ファイルを送るにはどうしますか?
slack_sdk の files_upload_v2 を使います。以前の files.upload は、2024年5月16日以降に作ったアプリでは使えず、2025年11月12日に提供が終わったと公式の変更履歴にあります。代わりは files.getUploadURLExternal と files.completeUploadExternal で、files_upload_v2 はこの2つを使う形です。

Q. Socket Mode の Bot は PC を閉じると止まりますか?
止まります。Socket Mode は動かしているプログラムが WebSocket でつながっている間だけ出来事を受け取れるので、常に動かすならサーバーやコンテナで動かします。

Q. Webhook の URL が漏れたらどうなりますか?
URL を知っている人なら誰でも、そのチャンネルに投稿できてしまいます。アプリの設定から Webhook を消して作り直し、新しい URL を環境変数に置き直します。

Q. 投稿にメンションを入れるには?
本文に <@ユーザーID> の形で書きます。最小の Bot のコードの <@{message['user']}> が、話しかけた人へのメンションです。

Q. 本物の Slack に送らずに試す方法はありますか?
この記事のように、WebClient の base_url や Webhook の URL を手元の模擬サーバーに向けると、送る JSON と例外の扱いをテストできます。本番に向けるときは base_url を指定しない形に戻します。

まとめ

  • Slack API は「送る」(Incoming Webhook・Web API)と「受け取る」(Events API・Socket Mode)に分かれる。通知だけなら Webhook、送り先を選ぶなら chat.postMessage、Bot なら Bolt。
  • アプリを作り、Bot Token Scopes に必要なスコープを足してインストールする。スコープを足したら再インストール。
  • エラーは e.response["error"] のコードで見分ける。not_in_channel は招待、missing_scope はスコープ、invalid_auth はトークンを確かめる。
  • 投稿は1チャンネルにおおむね1秒1件。429 は Retry-After を守り、slack_sdk なら RateLimitErrorRetryHandler で待てる(実測で約2.6秒・約5秒)。
  • トークン・Webhook の URL・Signing Secret はコードに書かず環境変数に置く。漏れたら無効にして作り直す。HTTP モードは署名を検証し、3秒以内に応答する。

参考・出典

確認日:2026年11月18日

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「Slack APIの使い方|Pythonで送信・Bot作成・Webhookの始め方」

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。

WE ARE HIRING

RJCで一緒に開発しながら、
成長を楽しみませんか?

RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!

  • 127日年間休日
  • 12時間平均残業時間
  • 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!

ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。

ABOUT RJC RJCがどんな会社か知る 考え方、研修、働き方、福利厚生、社員の前職まで。RJCのことが丸わかり! RJC丸わかりページへ JOB DESCRIPTION 仕事内容・待遇を見てみる 仕事内容、給与・待遇、選考の流れ。経験者も未経験も!応募前に知りたいこと、まとめました! 募集要項を見る ENTRY エントリーする エントリーは1〜2分・履歴書不要です。まずは話を聞いてみたい、という方でも歓迎です! エントリーフォームへ

成長のヒミツ、 ぜんぶ丸わかり