slack

Slack Web API スキル

Slack Web API を介して、Slack の読み取り、書き込み、検索、リアクション、ピン留め、会話の管理を行います。

重要：初回使用時の初期化

Slack の操作を実行する前に必ず、モード設定ファイルが存在するか確認してください。

cat ~/.agents/config/slack/config.env

ファイルが存在しない場合（または SLACK_MODE が含まれていない場合）は、ユーザーに使用するモードを尋ねる必要があります。次の 3 つの選択肢を提示してください。

1. トークン（macOS のみ）：Chrome からセッショントークンを直接抽出します。最速の方法です。Slack を開いた Chrome、AppleScript の有効化、uvx のインストールが必要です。
2. ブラウザー（クロスプラットフォーム）：ローカルの Playwright ブラウザーを使用して API 呼び出しを行います。macOS、Linux、Windows で動作します。SSO と 2FA に対応しています。
3. 自動検出（推奨）：Playwright セッションが存在する場合はブラウザーモードを自動的に使用し、それ以外の場合はトークンモードに切り替えます。両方の利点を活用できます。

ユーザーがモードを選択したら、すぐに保存してください。

mkdir -p ~/.agents/config/slack
echo 'SLACK_MODE=<selected_value>' > ~/.agents/config/slack/config.env

<selected_value> は token、browser、auto のいずれかです。

保存した後は、二度と尋ねないでください。 以降の実行では設定ファイルが存在するため、スキルは保存済みのモードを自動的に使用します。

ユーザーが browser モードを選択した場合は、ブラウザーセッションのセットアップも実行してください。

{SKILL_DIR}/scripts/slack-browser-session.sh login-manual

ユーザーが Slack にログインするためのブラウザーが画面に表示されます（SSO／2FA に対応）。セッションは保存され、以降のすべての API 呼び出しで再利用されます。

---

モードの選択

このスキルは 3 つのモードに対応しています。~/.agents/config/slack/config.env または SLACK_MODE 環境変数で設定します。

モード	値	動作
トークン	token	Chrome のセッショントークンを使って直接 curl を呼び出します。高速です。macOS のみ。
ブラウザー	browser	ローカルの Playwright ブラウザーセッションを介して API を呼び出します。クロスプラットフォーム対応です。
自動検出	auto	セッションがあればブラウザーを使用し、認証に失敗した場合はトークンに切り替えます。（デフォルト）

モードの設定

オプション 1：設定ファイル（永続的）

echo 'SLACK_MODE=token' > ~/.agents/config/slack/config.env
# or
echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env
# or
echo 'SLACK_MODE=auto' > ~/.agents/config/slack/config.env

オプション 2：環境変数（呼び出しごとの上書き）

SLACK_MODE=browser slack-api.sh conversations.history channel=C041RSY6DN2 limit=20

環境変数は設定ファイルより優先されます。

設定および状態ディレクトリ

スキルの設定と状態はすべて ~/.agents/config/slack/ に保存されます。

ファイル	用途
config.env	モードの選択（SLACK_MODE=auto|token|browser）
tokens.env	キャッシュされたセッショントークン（xoxc、xoxd、user-agent）
browser-session	アクティブなブラウザーセッション ID
sessions/<id>/storageState.json	Playwright セッションの Cookie と localStorage

このディレクトリは初回使用時に自動作成されます。

API ラッパー

すべての呼び出しは、単一の統合スクリプトを介して行われます。

{SKILL_DIR}/scripts/slack-api.sh <method> [key=value ...]

{SKILL_DIR} は、このスキルの読み込み時に指定されるベースディレクトリです（例：~/.agents/skills/slack）。

スクリプトは設定に基づいて、適切なモードへ自動的に振り分けます。メソッドの完全なリファレンスについては、references/api-methods.md を参照してください。

トークンモード（macOS）

トークンモードでは、起動中の Chrome ブラウザーからセッショントークンを抽出し、Slack Web API を直接 curl で呼び出します。

前提条件：

• Slack を app.slack.com で開いた Chrome が起動していること
• Chrome > 表示 > デベロッパー > Apple Events からの JavaScript を許可
• uvx がインストールされていること（brew install uv）

手動でのセットアップは不要です。初回の API 呼び出し時に、トークンが自動的に抽出されます。

ブラウザーモード（クロスプラットフォーム）

ブラウザーモードでは、ローカルの Playwright Chromium インスタンスを使用して Slack のセッションを維持します。API 呼び出しはブラウザーコンテキスト内で fetch() を介して行われるため、トークンを抽出する必要はありません。macOS、Linux、Windows で動作します。

前提条件：

• Node.js 18+ がインストールされていること
• Playwright は初回使用時に自動インストールされます（Chromium をダウンロードします。約 150 MB）

詳しいドキュメントについては、references/browser-mode.md を参照してください。

クイックスタート（ブラウザーモード）

# 1. モードを browser に設定
echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env

# 2. ブラウザーセッションを開始し、手動でログイン（SSO/2FA に対応）
{SKILL_DIR}/scripts/slack-browser-session.sh login-manual

# または、自動でメールアドレスとパスワードを使ってログイン
{SKILL_DIR}/scripts/slack-browser-session.sh start
{SKILL_DIR}/scripts/slack-browser-session.sh login [email protected] mypassword

# 3. ログインに成功したことを確認
{SKILL_DIR}/scripts/slack-browser-session.sh status

# 4. API 呼び出し（同じスクリプトを使用し、ブラウザー経由で自動的に処理されます）
{SKILL_DIR}/scripts/slack-api.sh conversations.history channel=C041RSY6DN2 limit=20

# 5. 完了したら終了
{SKILL_DIR}/scripts/slack-browser-session.sh stop

UI の自動化（API で対応していない機能）

ブラウザーモードでは、API がサポートしていない機能について、Slack のウェブ UI を直接操作することもできます。

# セッション ID を取得
SESSION_ID=$({SKILL_DIR}/scripts/slack-browser-session.sh get)

# 特定のチャンネルに移動
node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "goto", "url": "https://app.slack.com/client/TEAM_ID/CHANNEL_ID"}'

# スナップショットを取得して操作可能な要素を確認
node {SKILL_DIR}/scripts/playwright-bridge.js --function snapshot --session $SESSION_ID --input '{}'

# スナップショットの @e refs を使って UI 要素を操作
node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "click", "ref": "@e5"}'

# スクリーンショットを撮って視覚的に確認
node {SKILL_DIR}/scripts/playwright-bridge.js --function screenshot --session $SESSION_ID --input '{}'

UI 自動化の用途：

• Canvas の作成と編集（公開 API なし）
• ハドルでの操作（API なし）
• Workflow Builder の設定
• Slack Connect への招待
• 管理ページと設定ページ
• スクリーンショットによるメッセージの視覚的な確認

Slack URL の解析

Slack URL からチャンネルとタイムスタンプを抽出します。

https://{WORKSPACE}.slack.com/archives/{CHANNEL_ID}/p{TIMESTAMP_WITHOUT_DOT}

タイムスタンプの末尾 6 桁の前にピリオドを挿入します。

• URL：p1770725748342899 -> ts：1770725748.342899

スレッド内のメッセージの場合、URL に ?thread_ts= パラメーターが含まれることがあります。

読み取り操作

スレッドを読む

slack-api.sh conversations.replies channel=CHANNEL_ID ts=THREAD_TS limit=100

チャンネルの履歴を読む

slack-api.sh conversations.history channel=CHANNEL_ID limit=20

任意指定：時間範囲を指定するには oldest / latest（Unix タイムスタンプ）を使用します。

メッセージを検索

slack-api.sh search.messages query="search terms" count=10

修飾子：in:#channel、from:@user、before:YYYY-MM-DD、after:YYYY-MM-DD、has:link、has:reaction、has:pin。

名前でチャンネルを検索

slack-api.sh conversations.list types=public_channel limit=200 | python3 -c "import sys,json; channels=json.load(sys.stdin).get('channels',[]); matches=[c for c in channels if 'TARGET' in c['name']]; [print(f\"{c['id']} #{c['name']}\") for c in matches]"

ユーザーを検索

slack-api.sh users.info user=USER_ID

名前：.user.real_name または .user.profile.display_name。

ピン留めされた項目を一覧表示

slack-api.sh pins.list channel=CHANNEL_ID

チャンネルのメンバーを一覧表示

slack-api.sh conversations.members channel=CHANNEL_ID limit=100

書き込み操作

重要：書き込み操作の前に必ず確認を取ってください。

メッセージの送信、編集、削除、リアクションの追加／削除、ピン留め／ピン留め解除を行う前に、必ずユーザーにプレビューを表示して確認を求めてください。プレビューは次の形式にしてください。

宛先： #channel-name（DM の場合は @username） メッセージ： 正確なメッセージ本文 操作： 送信／編集／削除／リアクション／ピン留め（該当するもの）

送信しますか？（または「変更したい点はありますか？」）

ユーザーが明示的に確認するまで、書き込み API 呼び出しを実行しないでください。ユーザーが変更を希望する場合は、プレビューを更新して再度確認を求めてください。

メッセージを送信する

シンプルな 1 行メッセージの場合：

slack-api.sh chat.postMessage channel=CHANNEL_ID text="Hello world"

スレッドへの返信：thread_ts=PARENT_TS を追加します。チャンネルにもブロードキャストする場合：reply_broadcast=true を追加します。

書式付きの複数行メッセージを送信する

改行、太字、リスト、その他の mrkdwn 書式を含むメッセージには、text の代わりに blocks を使用します。ブラウザーモードでは、URLSearchParams を使用した text パラメーターで改行が二重にエスケープされるため、書式付きコンテンツの送信には blocks が確実です。

python で blocks JSON を作成し、API に渡します。

BLOCKS=$(python3 -c "
import json
blocks = [
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': '*Bold heading*'}},
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': 'Line 1\nLine 2\nLine 3'}},
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': '1. First item\n2. Second item'}}
]
print(json.dumps(blocks))
")
slack-api.sh chat.postMessage channel=CHANNEL_ID blocks="$BLOCKS" text="Fallback text"

text パラメーターは、通知や blocks を表示できないクライアント向けのフォールバックとして機能します。必ずプレーンテキストの要約を含めてください。

各 block の text フィールドは 3000 文字までです。これより長いメッセージは、複数の section block に分割してください。

メッセージを編集する

slack-api.sh chat.update channel=CHANNEL_ID ts=MESSAGE_TS text="Updated text"

メッセージを削除する

slack-api.sh chat.delete channel=CHANNEL_ID ts=MESSAGE_TS

リアクションを追加する

slack-api.sh reactions.add channel=CHANNEL_ID timestamp=MESSAGE_TS name=thumbsup

コロンなしの絵文字名を指定します。肌の色にも対応しています：thumbsup::skin-tone-3。

リアクションを削除する

slack-api.sh reactions.remove channel=CHANNEL_ID timestamp=MESSAGE_TS name=thumbsup

メッセージをピン留めする

slack-api.sh pins.add channel=CHANNEL_ID timestamp=MESSAGE_TS

メッセージのピン留めを解除する

slack-api.sh pins.remove channel=CHANNEL_ID timestamp=MESSAGE_TS

画像とファイルの取り扱い

メッセージにはファイルが含まれている場合があります。トークンモードの場合：

source ~/.agents/config/slack/tokens.env
curl -s "FILE_URL_PRIVATE" \
  -H "Authorization: Bearer ${SLACK_XOXC}" \
  -H "Cookie: d=${SLACK_XOXD}" \
  -o /tmp/slack-image-N.png

ブラウザーモードでは、ファイルの URL に移動してスクリーンショットを撮ります。

node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "goto", "url": "FILE_URL_PRIVATE"}'
node {SKILL_DIR}/scripts/playwright-bridge.js --function screenshot --session $SESSION_ID --input '{}'

次に Read ツールを使用して、ダウンロードした画像を表示します。

出力の書式設定

1. python3 -c "import sys,json; ..." で JSON を解析します
2. users.info（検索結果をキャッシュ）を使用して、ユーザー ID（U...）を実名に解決します
3. タイムスタンプと名前を付けてメッセージを表示します
4. <@U...> メンションを、解決済みの実名に置き換えます
5. Slack のマークアップ（エンティティ、リンク構文、チャンネル参照）をプレーンテキストにデコードします

レート制限

• API 呼び出しが連続する場合は、間に sleep 1 を追加します
• 大規模なデータセット（users.list）の一括ページネーションは行わないでください。セッションが終了します
• 一括取得よりも対象を絞ったクエリを優先します
• ブラウザーモードでは呼び出しごとに追加の待ち時間が発生します。可能な場合はまとめて実行してください

トークンの更新（トークンモード、自動）

トークンは完全に自動で更新されます。API ラッパーは以下を行います。

1. ~/.agents/config/slack/tokens.env が見つからない場合、自動で更新します
2. invalid_auth エラーが発生した場合、自動で更新して呼び出しを再試行します

トークンは、起動中の Chrome ブラウザーから抽出されます。

• xoxc：AppleScript 経由で Slack の localStorage から取得します
• xoxd：lsof と pycookiecheat 経由で Chrome の Cookie データベースから取得します

セットアップ

トークンモード（macOS）

1. Slack を app.slack.com で開いた状態で Chrome を起動します

2. Chrome > 表示 > デベロッパー > Apple Events からの JavaScript を許可 を有効にします

3. uv をインストールします：brew install uv

4. モードを設定します（任意。デフォルトでは自動検出が有効です）。

   echo 'SLACK_MODE=token' > ~/.agents/config/slack/config.env
   

ブラウザーモード（クロスプラットフォーム）

1. https://nodejs.org から Node.js 18 以降をインストールします

2. モードを設定して、セッションを開始します。

   echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env
   {SKILL_DIR}/scripts/slack-browser-session.sh login-manual
   

   Playwright と Chromium は初回使用時に自動でインストールされます。

自動検出（デフォルト）

設定は不要です。このスキルはまずアクティブなブラウザーセッションを確認し、Playwright 経由で API を呼び出します。ブラウザー呼び出しで認証エラー（invalid_auth、not_authed、no_teams_found）が返された場合は、自動的にトークンモードに切り替えます。これにより、ブラウザーセッションの期限が切れた場合もスムーズに復旧できます。

API リファレンス全体

ブックマーク、ユーザーグループ、リマインダー、絵文字、ファイル、ユーザープロフィールなどの追加メソッドについては、references/api-methods.md を参照してください。

エラー処理

• not_in_channel：ユーザーはこのチャンネルにアクセスできません
• channel_not_found：チャンネル ID が無効です
• invalid_auth：トークンの期限が切れています。自動更新を試みます（トークンモード）
• ratelimited：5 秒待ってから再試行します
• cant_update_message / cant_delete_message：自分のメッセージのみ変更できます
• no_browser_session：アクティブなブラウザーセッションがありません。slack-browser-session.sh start を実行してください
• node_not_found：Node.js がインストールされていません。https://nodejs.org からインストールしてください
• no_teams_found：Slack がブラウザーでワークスペースのデータを読み込んでいません。待ってから再試行してください
• 自動フォールバック：自動モードでは、ブラウザー呼び出しで invalid_auth、not_authed、no_teams_found が返された場合、スキルは自動的にトークンモード経由で再試行します。手動での対応は不要です。