Slack アプリ開発へようこそ！
この記事では、ショートカット、モーダルのようなインタラクティブな機能を Bolt for JavaScript を使ってどのように実装すればよいかを解説します。
なお、この記事で紹介するのは、BIT VALLEY 2020 のための用意されたデモアプリです。
BIT VALLEY での講演は YouTube で公開されていますので、こちらからご覧ください。
この記事で実装するアプリ
ここで扱うサンプルプロジェクトは、ヘルプデスクチームが提供するアプリを想定したサンプルです。シンプルではありつつも、Slack プラットフォームの最新の機能をうまく活用しているので、これをベースに拡張することで実際に使えるアプリに進化させることができるでしょう。
以下のアニメーションで、どのようなアプリなのかをみてみましょう。
ショートカットでモーダルを起動
エンドユーザーは、Slack の最下部の入力ボックスからショットカットを起動し、モーダルウィンドウを開くことができます。
複数画面を行き来できるモーダル
エンドユーザーは、このモーダル上でまずカテゴリを選択します。ユーザーがカテゴリを選択すると、モーダルは即座に自分自身の表示状態を切り替えて、選択されたカテゴリに対応した入力フォームを表示します。「カテゴリ選択に戻る」ボタンを押すと、一つ前の画面に戻ることもできます。
カスタムの入力チェック
このモーダルを送信すると、Slack の UI が標準で持っている必須入力チェックなどに加えて、サーバーサイドがカスタムの入力チェック処理を行います。ここでは件名の桁数と希望納品日が未来日かどうかのチェックをしています。
通知を送信
データ送信を受け付けたら、ヘルプデスクチームのチャンネルや関係者の DM にメッセージを送信することができます。
ホームタブを更新
また、ホームタブというユーザーごとにカスタムの情報を表示できるエリアに、このユーザーのこれまでの申請履歴を表示しています。
使われている Slack プラットフォームの機能
このアプリは以下のような Slack プラットフォームの最新の機能を使って実装されています。
- ブロックキット: ブロックキットはリッチなユーザーインターフェースを実装するための Slack の UI フレームワークです。Slack アプリの開発者の視点で見るとブロックキットは予め決められた JSON のデータ構造です。アプリ側がこれに従うことで Slack がデスクトップ・モバイルに最適な形でレンダリングします。
- ショートカット: グローバルショートカットは Slack のどこからでも呼び出せる処理です。ユーザーは、最下部のメッセージ投稿 UI、または、最上部の検索メニューから呼び出すことができます。
- モーダル: モーダルはブロックキットを使って構成するポップアップウィンドウです。ユーザーから入力内容を収集したり、情報を整理された形で表示したりするために利用されます。また、複数のステップの遷移を実装したり、複数モーダルを重ねたりすることもできます。
- ホームタブ: ユーザーごとに個別の情報を表示するためのエリアです。自分のタスクや予定を表示したり、ダッシュボードのようなものを表示するために利用されます。
Bolt for JavaScript
Bolt for JavaScript (ボルト) は、公式のフルスタックな Slack アプリ開発フレームワークです。全ての新しいプラットフォーム機能がサポートされており、また Slack アプリで必要となる非機能要件に予めフレームワーク側で対応しています：
- Slack からのリクエストを検証: Slack アプリのエンドポイントは公開された URL である必要があるため、受信したリクエストが本当に Slack からのリクエストかどうかを検証することはセキュリティのために重要です。Bolt を使うと Signing Secret の値を設定しておくだけで、この検証が自動的に有効になります。
- リクエストを適切に分岐: Slack からのリクエストを適切なリスナー関数に実行させます。Web アプリフレームワークのルーティング機能のようなインターフェースで簡単にこの分岐を設定することができます。
- ペイロードの形式の差異を吸収: 歴史的経緯から Slack API のペイロードの形式は機能によって若干異なりますが、Bolt はそれらを適切にパーズした上で、その内容をミドルウェアやリスナー関数に統一的な形式で引き渡します。
- 無限ループに陥らないように予め制御: イベント API を使っていると、ボットユーザー自身の発言に再度反応して無限ループしてしまうという失敗がありがちですが、Bolt を使っていると予めループしないよう制御してくれます。
- 複数ワークスペース対応: 開発用ワークスペース以外にもインストールできるアプリとして提供するために必要な OAuth フローの実装や、各リクエストごとに適切なトークンを選択するロジックを簡単に実装できる仕組みを提供しています。
このように Bolt を使うことで、アプリの本質的なロジック以外の様々なことへの対応がシンプルになります。
このアプリを実装するための全ステップ
プロジェクトをセットアップする
git clone [email protected]:seratch/bit-valley-2020-slack-bolt-app.git
cd bit-valley-2020-slack-bolt-app/
node --version # Node v10.13 かそれよりも新しいバージョンが必須です
npm i # 依存パッケージをインストール
code . # Visual Studio Code を使ってプロジェクトを開きます
Slack アプリの設定を作る
https://api.slack.com/apps にブラウザでアクセスして、新しい Slack アプリの設定をつくります。
このブラウザで、Slack ワークスペースにログインしているか確認し、その上で先ほどの URL から Slack アプリを作ります。
必要な Bot Token Scopes を設定
アプリを作ったら OAuth & Permissions というページに遷移し、Bot Token Scopes というセクションまでスクロールします。そして、以下の権限を追加してください。
-
commandsは、新しいショートカットの追加に必要です。 -
chat:writeはchat.postMessageAPI というメッセージ投稿の API を使うために必要です。 -
chat:write.publicは、任意のパブリックチャンネルにボットユーザーを招待することなくchat.postMessageAPI を実行するために必要です。 -
im:writeはconversations.openAPI という新しい DM を開始するための API を使うために必要です。
ボットユーザーに適切な名前をつける
インストールする前に App Home ページで、ボットユーザーにわかりやすい名前をつけるとよいでしょう。 Basic Information の最下部でアプリのアイコンや説明をなどをカスタマイズすることもできます。
ホームタブ機能を有効にする
デフォルトではホームタブの機能は有効になっていないので、 App Home ページで有効にしておいてください。
アプリをワークスペースにインストールする
「Development Slack Workspace」で使用する限りにおいては、OAuth フローを実装しなくても OAuth アクセストークンを発行して、アプリをそのワークスペースで有効化することができます。
Install App ページから、インストールボタンをクリックし、OAuth フローを完了させてください。戻ってきた画面で Bot User OAuth Access Token として表されているアクセストークンをアプリ起動時に指定します。
もし、複数ワークスペースにインストール可能なアプリを実装することに興味があれば、Bolt for JavaScript のドキュメントを参考にしてみてください。
Bolt アプリを立ち上げる
ローカルで Bolt アプリを起動するには、以下のステップに従ってください：
- プロジェクトのルートディレクトリに
.envファイルを作って、必要な情報を設定 - Node.js 10.13 かそれより新しいバージョンを使っているか確認 (
node --version) -
npm installを実行して依存ライブラリをインストール -
npm run localを実行して、アプリを起動 - ngrok をインストールしていなければインストール - https://ngrok.com/
- 別のターミナルで
ngrok http 3000を実行して公開エンドポイントを立ち上げる
.env を配置して Bot Token と Signing Secret を設定
SLACK_BOT_TOKEN=xoxb-111-111-xxx
SLACK_SIGNING_SECRET=xxx
ローカルアプリを起動
node --version # v10.13.0 以上
npm install
npm run local # 起動すると http://localhost:3000/slack/events でリクエストを受け付けます
ngrok を Slack からのリクエストをフォワードするために起動
ngrok をまだインストールしていなければ、ウェブサイトからダウンロードして設定します。以下のステップで、適切に設定できたか確認します。
# ローカルでアプリが立ち上がっていることを確認
curl -I -XPOST http://localhost:3000/slack/events # HTTP/1.1 401 Unauthorized が返ってくるはず
# 別のターミナルで実行
./ngrok http 3000
# ngrok の有償プランを使っているなら以下のように固定のサブドメインを指定できます
./ngrok http 3000 --subdomain {whatever-you-want}
# 再度、公開エンドポイントからリクエストをして、同じように 401 が返ってくるか確認
curl -I -XPOST https://{your random subdomain here}.ngrok.io/slack/events # HTTP/1.1 401 Unauthorized が返ってくれば OK
Request URL を設定して、ショートカットを追加
- https://api.slack.comc/apps にアクセスしてアプリを選択
- Interactivity & Shortcuts ページへ移動
- Interactivy 機能が無効になっているのを有効にする
-
https://{your random subdomain here}.ngrok.io/slack/eventsを Request URL として設定 - Global のショートカットを Callback ID:
new-helpdesk-requestで作成 - 最下部の Save Changes ボタンを押すのを忘れずに
リスナー関数を実装する
このアプリでは以下のリスナー関数を実装しています。
-
グローバルショートカットのリスナー関数 を
new-helpdesk-requestという Callback ID に反応するよう設定 -
セレクトメニューでの選択に対するリスナー関数 を
helpdesk-request-modal-category-selectionという Action ID に反応するよう設定 -
「カテゴリ選択へ戻る」ボタンクリックに対するリスナー関数 を
helpdesk-request-modal-resetという Action ID に反応するよう設定 -
モーダル送信に対するリスナー関数 を
helpdesk-request-modalという Callback ID に反応するよう設定
小技: Block Kit のプレビューツール
ブロックキットビルダー というブラウザから使えるブロックキットのプレビューツールがあります。実際にアプリに blocks を組み込む前に、このツールを使って表示を調整すると効率的に UI を改善できるでしょう。
まとめ
-
https://api.slack.com/apps から Slack アプリの設定を行います
- そのブラウザで Slack ワークスペースにログインしている必要があります
- 必要な権限を設定する
- "OAuth & Permissions" ページで Bot Token Scopes を設定します
- Interactivity, Events Subscriptions, Home tab 等の機能を有効にします
- Development Slack Workspace にアプリをインストールします
- "Bot User OAuth Access Token" を取得します
- Bolt アプリをローカルで作成します
-
SLACK_BOT_TOKEN,SLACK_SIGNING_SECRETという環境変数、または .env ファイルを設定します -
app.start()で Web サーバープロセスを起動します - デフォルトでは
POST http://localhost:3000/slack/eventsで全てのリクエストを受けます
-
- 公開されたエンドポイントを設定して、Slack からのリクエストを受け付けられるようにします
- ngrok かその他類似のソリューションを使います
- 必要なリスナー関数を実装します
- ngrok を使っているなら
http://localhost:4040を確認すると捗るでしょう - 標準出力にエラーメッセージが出ていることもあります
- Bolt for JS のドキュメントは全て日本語化されています
- ngrok を使っているなら
- Slack アプリ開発を楽しんでください！