mcpField
S
setting-up-support-slack-locally

setting-up-support-slack-locally

github.com/posthog開発9562 回インストール今日更新
リポジトリ

setting-up-support-slack-locally について

SupportHogのローカル開発環境を一時的なSlackワークスペースに接続する手順です。ブラウザー経由のOAuthはlocalhostで行い、受信イベントのみパブリックトンネルに転送します。

主な機能

  1. 01OAuthとイベントの到達経路を分離
  2. 02Slackアプリの認証情報とスコープ設定
  3. 03トンネル経由のイベント・操作コールバック
  4. 04対応するSlackイベントの購読
  5. 05メッセージのサポートチケット化をテスト

活用シーン

  1. 01Slackサポート連携のローカル開発
  2. 02チャンネル投稿からのチケット作成確認
  3. 03チケット返信のSlackスレッド投稿テスト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/posthog/ai-plugin --skill setting-up-support-slack-locally

インストール後、Claude Code で/setting-up-support-slack-locallyを入力して読み込まれたか確認します。

同梱ファイルreferences/troubleshooting.md

詳細

Support Slack をローカルでセットアップする

Slack は SaaS 専用です。そのため「ローカル」とは、OAuth とイベントがノートパソコンに届く、一時的な Slack ワークスペースとアプリを指します。ほとんどの障害を避けられる、見落としやすいポイントが 1 つあります。OAuth 接続とイベント Webhook では到達性の要件が逆なので、それぞれ別の接続先を指定します。

  • OAuth 接続はブラウザーを介して行われます。ブラウザーがリダイレクト先にアクセスするため、localhost に到達できます。トンネルは必要ありません。
  • 受信イベント（Slack がメッセージを POST し、チケットに変換する処理）は、Slack のクラウドからのサーバー間通信です。Slack は localhost に到達できないため、ここではパブリックトンネルが必要です。

アプリ全体と OAuth フローは localhost 上に保ち、Event Subscriptions（および Interactivity）のみをトンネルに向けます。これにより、トンネルを SPA 全体ではなく、低頻度の Slack イベント POST のみに使用するため、無料プランのトンネルのレート制限も回避できます。

これは、一般的なSlack のローカルセットアップガイドの conversations／SupportHog 向けのバリエーションです。このガイドでは、PostHog Desktop／notifications Slack アプリ（SLACK_APP_*、/integrations/slack/callback）を扱っています。Conversations では独自の SUPPORT_SLACK_* 認証情報と /api/conversations/v1/slack/* ルートを使用しますが、トンネルと SITE_URL の仕組みは同じです。

エンドポイント

すべて products/conversations/backend/api/urls.py にあり、プレフィックスは /api/conversations/ です。

ルート用途到達元
v1/slack/authorizeSlack OAuth URL を返します（認証が必要）ブラウザー（localhost）
v1/slack/callbackOAuth リダイレクト先。SITE_URL から構築され、https は強制されませんブラウザー（localhost）
v1/slack/events受信イベント WebhookSlack のサーバー（トンネル）
v1/slack/interactivityインタラクティブコンポーネントのコールバックSlack のサーバー（トンネル）

コールバックには、SITE_URL が解決されるオリジンでの認証済みセッションが必要です。セッション Cookie はオリジンごとに異なるためです。SITE_URL を localhost に設定して、そこでログインしてください。そうすれば、コールバックでもセッションが維持されます。

ステップ 1 — 認証情報

SUPPORT_SLACK_APP_CLIENT_ID、SUPPORT_SLACK_APP_CLIENT_SECRET、SUPPORT_SLACK_SIGNING_SECRET は django-constance の動的設定（posthog/settings/dynamic_settings.py）で、一致する環境変数がデフォルト値として使われます。クライアント ID が空の場合、「Support Slack OAuth client ID is not configured」というメッセージが表示されます。Slack アプリの値を .env.local（Git 追跡対象外）に設定し、バックエンドを再起動してください。

SUPPORT_SLACK_APP_CLIENT_ID=<client id>
SUPPORT_SLACK_APP_CLIENT_SECRET=<client secret>
SUPPORT_SLACK_SIGNING_SECRET=<signing secret>

Constance は値をデータベースに保存し、保存済みの値は環境変数のデフォルト値より優先されます。再起動後も未設定と表示される場合は、/admin/constance/config/ で空の保存済み値を確認し、そこで設定してください。

ステップ 2 — Slack アプリ

api.slack.com/apps で使い捨てのワークスペースにアプリを作成し、次の手順を行います。

  1. App Home → bot user を有効にします（表示名を設定します）。これを行わないと、「requesting permission to install a bot ... but it's not currently configured with a bot」というエラーが表示され、インストールに失敗します。
  2. OAuth & Permissions → Bot Token Scopes — フローで次のスコープが要求されます（products/conversations/backend/api/slack_oauth.py の SUPPORTHOG_SLACK_SCOPES から取得します）：channels:history、channels:read、chat:write、 chat:write.customize、files:read、files:write、groups:history、groups:read、reactions:read、 users:read、users:read.email。添付ファイルには双方向で 2 つの files: スコープが必要なため、これらを付与せずにインストールしたワークスペースでは、サポート設定に「再接続」バナーが表示されます。
  3. OAuth & Permissions → Redirect URLs — http://localhost:8010/api/conversations/v1/slack/callback を追加して保存します。Slack が通常の HTTP の localhost URL を拒否する場合は、コールバックにもトンネル URL を使い、トンネルのオリジンで一度ログインします（references/troubleshooting.md を参照）。
  4. Basic Information から Client ID、Client Secret、Signing Secret をコピーし、.env.local に追加します（ステップ 1）。

ステップ 3 — 受信イベント用のトンネル

Caddy の 8010 に接続し、上流の Host ヘッダーを localhost に書き換える HTTPS トンネルを実行します（開発用 Caddy は localhost ホストへのリクエストにのみ応答します。書き換えないと、空の 200 と白いページが表示されます）。

ngrok http --host-header=localhost 8010
# or, free with no rate limit:
cloudflared tunnel --url http://localhost:8010 --http-host-header localhost

Caddy だけでなく Django にも到達していることを確認します。

curl -sS https://<tunnel-host>/_preflight | head -c 120   # want JSON, server: granian

次に、Slack アプリで Event Subscriptions → Request URL（ボタンをテストする場合は Interactivity → Request URL も）を https://<tunnel-host>/api/conversations/v1/slack/events（および .../interactivity）に設定します。 Slack は保存時に同期的な url_verification チャレンジを送信するため、バックエンドを起動しておく必要があります。ハンドラーが自動的に応答を返します。

Request URL の設定だけでは検証に成功するだけで、イベントを購読するまでは何も配信されません。 Event Subscriptions → Subscribe to bot events で、バックエンドが処理するイベント（products/conversations/backend/api/slack_events.py の SUPPORT_EVENT_TYPES）を追加します。

  • app_mention
  • message.channels（プライベートチャンネルでは message.groups も追加します）。どちらも内部の message イベントとして届きます
  • reaction_added
  • member_joined_channel、member_left_channel

スコープやイベントを変更した後は、新しい権限を有効にするためアプリを再インストールします。

ステップ 4 — 接続してテスト

http://localhost:8010 でアプリを開いてログインし、サポート設定に移動して Slack を接続します。OAuth の往復処理は localhost 上で完了します。次に、開発用ワークスペースのチャンネルにボットを招待してメッセージを投稿します。メッセージはチケットとして届き、チケットからの返信はスレッドに投稿されます。

確認しておきたい失敗ケース（白い画面、「Network error」、リダイレクトの不一致、リージョンのルーティング）については、references/troubleshooting.md を参照してください。

コメント

Markdown 対応