Slack Block Kit Builderの使い方:テンプレート、プレビュー、ペイロード
SlackのBlock Kit Builder(app.slack.com/block-kit-builder)では、テンプレートを選んでブロックを足し、DesktopとMobileでプレビューして、Webhookやchat.postMessage用のJSONをコピーできます。今のビルダーの使い方、動くデプロイの通知の例、送る手順をまとめました。
On this page
SlackのBlock Kit Builderは、Slackのメッセージ用のJSONを目で見ながら作れる無料のエディターで、場所は app.slack.com/block-kit-builder です。Slackにサインインした状態で開き、Templates タブでテンプレートを選ぶか Builder タブを開いて、左のパネルからブロックを足します。真ん中の列にメッセージの見た目が、右の列にJSONが出ます。見た目がよければ Copy Payload をクリックし、そのJSONをIncoming Webhookか chat.postMessage で送ります。アプリも有料プランもいりません。
9月28日に今のビルダーを一通り使い、10月4日には壊れたペイロード16個をビルダーで試しました。下のスクリーンショットはそのときのものです。私たちは無料のSlackツールも作っていて、MarkdownをSlack用に変換するツールの出力はそのままsectionブロックに入れられます。
Block Kit Builderでできること
Block Kitは、アプリのメッセージ、モーダル、App HomeタブのためのSlackのJSON形式です。進捗バーのブロックはないので、Slackの進捗バーは、アプリが chat.update で描き直すテキストです。メッセージはブロックの並びでできています。ヘッダー、テキストのセクション、画像、ボタン、区切り線に加えて、表やカードのような新しいブロックもあります。エージェントが使うplanとtask cardのブロックについては、task cardのテストで、それぞれが受け付けるステータスと表示を確かめています。エージェントが答えている間に出る「is working...」の行はブロックではなく、別のAPIの呼び出しで出します。これはassistant.threads.setStatusとagents.sessions.setStatusの比較で試しました。ビルダーはこのJSONを目で見て編集する道具です。チャンネルにメッセージを送るのはビルダーではなく、Webhookやアプリです。また、1つのメッセージの2行のあいだに画像を入れる方法はこれしかなく、ふつうのメッセージ欄ではできません。Slackのインライン画像のテスト(英語)のとおりです。テキストではなくメディアを見せるブロックが2つあります。動画ブロックはYouTubeの埋め込みか、アプリが登録したドメインのプレーヤーを再生し、ファイルブロックはリモートのファイルやアップロードしたファイルのカードを出します。
Slack Block Kit Builderの使い方
- ビルダーを開きます。
app.slack.com/block-kit-builderにアクセスします。複数のワークスペースに入っているなら、右上のメニューでワークスペースを選びます。 - テンプレートから始めます。 Templates タブには、Alerts、Approval、Notification、Onboarding、Poll、Rich Markdownなどのグループがあります。クリックするとビルダーで開きます。
- ブロックを足す、変えます。 Builder タブの左のパネルにブロックの種類が並んでいます。Agents、Markdown、Section、Actions、Condition、Input、Structure、Rich Text、Image、Card and Carousel、Callout、Table、Data Visualization、Container、Referenceです。クリックすると追加されます。右の Payload パネルに直接書いてもよく、編集するとプレビューがすぐ変わります。
- 表示先を選びます。 プレビューの上の1つ目のメニューで、Message Preview、Attachment Preview、Modal Preview、App Home Preview を切り替えます。モーダルで使えるブロックがメッセージでは使えないこともあり、ビルダーはそれを表示します。長い文の扱いは2つのメッセージ形式で違います。「もっと見る」のテスト(英語)では、Slackはattachmentを5行で「Show more」の後ろに折りたたみ、ブロックは全文を表示しました。attachmentの色の帯については、attachmentの色のテストに、Slackが残す
colorの値と捨てる値をまとめています。 - DesktopとMobileを確かめます。 2つ目のメニューで、プレビューを Desktop と Mobile で切り替えます。長いボタンの列や横に広い画像は、スマホでは見え方が変わります。
- ボタンを試します。 プレビューでボタンをクリックするかメニューの項目を選び、Actions Preview タブを開きます。アプリが受け取る
block_actionsのペイロードが出ます。ボタンの3つのスタイルと、ほかの色を指定したときのエラーはボタンのスタイルのテストにあります。セレクトメニューについては、external_selectの選択肢を返す処理にかけられる時間も含めてセレクトメニューのテストを、本物のクリックで届くペイロードとresponse_urlが何回使えるかはSlackのインタラクティブなペイロードのテストをご覧ください。アプリを自分のノートパソコンで動かしながらクリックを受け取るには、トンネルかSocket Modeが必要です。ngrok、Cloudflareのトンネル、Socket Modeを比べました。 - JSONをコピーします。 Copy Payload (JSONの上のコピーのアイコン)をクリックします。ごみ箱のアイコン(Clear Blocks)を押すと、キャンバスが空になります。

例:ボタン付きのデプロイの通知
ビルダーで次のメッセージを作りました。ヘッダー、mrkdwn のテキストとリンクを入れたセクション、contextの行、2つのボタンがあります。
{
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Deploy finished"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*api-server* v2.14.0 is live on *production*.\nTook _4 min 12 s_. <https://slack.green|View the release notes>"
}
},
{
"type": "context",
"elements": [
{
"type": "mrkdwn",
"text": "Triggered by the nightly pipeline"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "Open dashboard"
},
"url": "https://slack.green",
"action_id": "open_dashboard"
},
{
"type": "button",
"style": "danger",
"text": {
"type": "plain_text",
"text": "Roll back"
},
"value": "rollback_v2140",
"action_id": "rollback"
}
]
}
]
}
プレビューで Roll back をクリックして Actions Preview を開くと、アプリが受け取るペイロードに "action_id": "rollback"、"value": "rollback_v2140"、"style": "danger" が入っていました。
url を持つボタンは、そのリンクを開きます。value だけのボタンのクリックを受け取るには、インタラクティブ機能をオンにしたアプリが必要です。Incoming Webhookだけでは扱えません。そのアプリが ack() を呼ばないと、Slackはボタンの横に警告の三角を出します。Boltのエラー処理のテストで試したケースの1つです。ボタンを並べる代わりに「...」のボタンの後ろに5つまでの操作をまとめるなら、オーバーフローメニューを使います。
Webhookでペイロードを送る
Incoming Webhookも同じJSONを受け付けます。いちばん外側に text も入れましょう。ブロックのあるメッセージでは、Slackはこれを通知とスクリーンリーダーに使います。
curl -X POST -H "Content-Type: application/json" \
-d '{"text": "Deploy finished: api-server v2.14.0",
"blocks": [{"type": "section", "text": {"type": "mrkdwn",
"text": "*api-server* v2.14.0 is live on *production*."}}]}' \
"$SLACK_WEBHOOK_URL"
ここにある blocks の配列を、Copy Payload でコピーした配列とまるごと入れ替えます。Webhookの準備はSlackのWebhookを作る方法に、ほかのリクエストの形とエラーコードはSlackのWebhookのcurlの例にあります。ボットトークンを使うなら、同じ本文に channel を加えて chat.postMessage に送ります。Slackが invalid_blocks を返したら、invalid_blocksのテストにそれぞれの上限と返るエラーの文をまとめています。
Block Kit Builderが見つけないエラー
10月4日に、ペイロード16個をビルダーで開きました。どれもSlackのAPIにすでに送ったことのあるケースで、ビルダーの警告とSlackの返事を比べました。ビルダーが指摘したのは、action_id と block_id の重複、51個のブロック、ダウンロードできない画像のURL、テキストもfieldsもないセクション、10個を超えるfieldsです。長さのエラーでは、赤い帯に出るのは「failed to match all allowed schemas」だけです。上限は、その行の横の赤い印にカーソルを合わせると出ます。
| ペイロード | Block Kit Builder | SlackのAPI |
|---|---|---|
| 151文字のヘッダー | 帯:failed to match all allowed schemas。ホバー:must be less than 151 characters | invalid_blocks、must be less than 151 characters |
1つのactionsブロックに同じ action_id | action_id "x" already exists | invalid_blocks |
| 51個のブロック | no more than 50 items allowed | invalid_blocks |
| 12,001文字のmarkdownブロック | 警告なし | msg_too_long (WebhookはHTTP 500) |
| 12,000文字のmarkdownブロックと3,000文字のセクション | 警告なし | chat.postMessage:msg_blocks_too_long |
ビルダーが見るのはブロックだけで、いちばん外側の text やWebhookの返事は見ません。私たちのBlock Kitチェッカーは Copy Payload のJSONを受け取り、送り方ごとにSlackが返す行を表示します。Open in Block Kit Builder ボタンで、直したブロックをビルダーに戻せます。
Block Kit Builderのリンクを共有する
ビルダーはペイロードをページのアドレスに持っています。# のあとがURLエンコードしたJSONです。アドレスバーをコピーすれば、Slackにサインインしている人なら誰でも同じメッセージを見られます。このリンクはコードからも作れます。
import json
import urllib.parse
blocks = {"blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": "*Hello* from a link"}}]}
url = "https://app.slack.com/block-kit-builder#" + urllib.parse.quote(json.dumps(blocks, separators=(",", ":")))
print(url)
9月28日にこのスクリプトが出力したリンクを開くと、ビルダーにメッセージが読み込まれました。
Block Kit Builderのコツ
mrkdwn で書きます。*太字*、_斜体_、<https://example.com|リンクの文字> です。**太字** や [文字](url) のような普通のMarkdownは、そのまま文字で出ます。書き方と、普通のMarkdownを読めるmarkdownブロックについてはSlack Block KitのMarkdownをご覧ください。手元の文を変換したり、1つのmrkdwnの文をプレビューしたりするならMarkdownをSlack用に変換するツールを使います。<@U0123ABCD> と書きます。SlackのWebhookでユーザーをメンションする方法をご覧ください。<!date^1790553600^{date_short} at {time}|fallback> と書きます。Slackのタイムスタンプ生成ツールでこの文字列を作れます。よくある質問
Slack Block Kit Builderは無料ですか?
はい。開くにはSlackのアカウントが必要ですが、アプリも有料プランもいりません。
Block Kit Builderからチャンネルにメッセージを送れますか?
いいえ。JSONを作ってプレビューするだけです。送るのはWebhook、chat.postMessage、ワークフローです。C#なら、SlackNetで同じブロックを型付きのクラスから作れます。C#でのSlack APIのテストをご覧ください。
Block Kit Builderでボタンを追加するには?
左のパネルからActionsブロックを足すか、セクションのaccessoryとしてボタンを付けます。リンクを開くなら url を、アプリで処理するなら action_id と value を指定します。アプリがBoltの respond() でクリックに答えると、replace_original=False を渡さない限り、返事はボタンのあるメッセージを置き換えます。sayとrespondのテストでわかったことです。
モーダルやApp HomeにもBlock Kit Builderを使えますか?
はい。プレビューの上の表示先のメニューを、Modal PreviewかApp Home Previewに切り替えます。アプリからモーダルを開くには、クリックからおよそ3秒以内に views.open を呼びます。この時間はexpired_trigger_idのテストで測りました。
関連記事
Slack の xoxc トークンと xoxd トークンの正体と仕組み
xoxc は Slack ウェブクライアントのトークン、xoxd はセッション Cookie です。片方だけでは動きません。各接頭辞の意味と認証の仕組みを解説します。
Slackのメッセージが灰色になるのはなぜ?(検証済み)
Slackのメッセージが灰色なのは、まだSlackに届いていないからです。接続を切って灰色の文字を測り、問題のない灰色の行も確かめました。
Slackで表示名を変える方法(検証済み)
Slackの表示名はプロフィールの編集で変えられます。どこに表示されるか、Slackがどんな名前を断るか、変更が反映されないのはなぜかを試しました。