Slack 連携

Crowi のページリンクを Slack で unfurl (リッチプレビュー) する設定

@crowi/plugin-slack を有効にすると、Crowi のページ URL を Slack に貼ったときに unfurl (リッチプレビュー) されるようになります。公開ページはタイトル・抜粋・パンくず・更新日時のカードに、非公開ページは内容を伏せた最小カードに展開されます。現在の Slack 連携でできるのは、この unfurl だけです (Slack への通知転送はまだありません)。

仕組み

Slack 連携は他のプラグインと同様、runner プロジェクトに @crowi/plugin-slack を追加して有効化します。

プラグインは Slack からのイベントを受け取る口を 1 つ公開します。この口は Crowi のログインを要求しませんが、Slack のリクエスト署名 (リプレイ対策つき) で検証され、署名が一致しないリクエストは拒否されます。

セットアップ

1. プラグインを有効化する

runner プロジェクトの package.json の依存に @crowi/plugin-slack を追加し、crowi.config.json の plugins 配列に列挙します。

{
  "plugins": ["@crowi/plugin-slack"]
}

有効化すると、管理サイドバーの プラットフォームサービス セクションに「Slack」設定が現れます。

2. manifest を生成する

管理画面の Slack 設定を開き、「Generate Slack App manifest」 ボタンを押すと、Slack App の manifest JSON が表示されます。ダイアログの内容をコピーしてください。ボタンの下には Slack アプリの新規作成ページ (api.slack.com/apps) へのリンクも表示されます。 manifest には次の値が埋め込まれています。

アプリ名 / bot 名 = この wiki の名前 (app:title)
event_subscriptions.request_url = {CLIENT_URL}/api/plugins/@crowi/plugin-slack/events
購読する bot イベント = link_shared
unfurl 対象ドメイン = この Crowi インスタンスのホスト
OAuth スコープ (最小権限) = links:read / links:write / chat:write

3. Slack App を自分たちで作成する

Slack App は 自分たちのワークスペース用に自分で作成 します (公開アプリや Marketplace アプリを使うわけではありません)。Slack の Your Apps で 「Create New App」 → 「From an app manifest」 を選び、インストール先のワークスペースを選んで、step 2 でコピーした manifest を貼り付けて作成します。

Slack 側でアプリを作成・インストールするには、対象ワークスペースでアプリのインストールが許可されている (ワークスペース管理者である、または承認を得られる) 必要があります。

4. ワークスペースにインストールして token を取得する

作成したアプリの設定画面で、左メニューの 「Install App」 を開き、 「Install to Workspace」 で自分たちのワークスペースにインストールします (初回はアプリの権限への承認を求められます)。インストールすると同じ 「Install App」 ページに Bot User OAuth Token (xoxb-…) が表示されるので、これをコピーします。Signing Secret は 「Basic Information」 ページから取得します。

この 2 つを Crowi の管理画面の Slack 設定に入力して保存します。

設定項目	取得元	機密
Bot User OAuth Token (`xoxb-…`)	「Install App」 (インストール後に表示)	はい
Signing Secret	「Basic Information」	はい

どちらも @sensitive 設定として扱われ、CROWI_ENCRYPTION_KEY が設定されていれば暗号化されて保存されます (詳細は機密設定の暗号化)。保存すると reconfigure が走り、 サーバを再起動しなくても Slack クライアントが再構築されます。

5. 動作確認

公開ページの URL を Slack のチャンネルに貼ると、タイトル・抜粋・パンくず・更新日時のカードが展開されれば成功です。

データ漏洩ガード

Slack の unfurl はチャンネルにいる全員に見えるため、可視性に注意が必要です。内容は次のルールで制御されます。

公開 (Public) ページ のみ、タイトル + 抜粋 + パンくず + 更新日時のリッチカードを表示します。
それ以外 (リンクを知っている人のみ / 特定ユーザー / 自分のみ) は、「🔒 Restricted page」という 本文を含まない 最小カードになります。

Slack のユーザーと Crowi のユーザーを紐付けて公開範囲を判定する unfurl は行いません。

トラブルシューティング

症状	確認すること
unfurl が出ない	Slack App がワークスペースにインストールされているか。manifest の unfurl ドメインがこのインスタンスのホストと一致しているか
Slack から検証エラー	`request_url` がインターネットから到達可能か (dev はトンネルが必要)。signing secret が正しく入力されているか
非公開ページが空カードになる	仕様です。公開ページのみリッチ unfurl されます
設定変更が反映されない	保存後に `reconfigure` が走るため通常は即時反映。bot token を貼り直して再保存してください