Slack Block Kit Builder: How to Use It, Templates, Payload
Slack's Block Kit Builder at app.slack.com/block-kit-builder lets you pick a template, add blocks, preview the message on Desktop or Mobile, and copy the JSON payload for a webhook or chat.postMessage. A walk through the current builder, a working deploy message, and the steps to send it.
On this page
Slack's Block Kit Builder is the free visual editor for Slack message JSON at app.slack.com/block-kit-builder. Open it while signed in to Slack, pick a template on the Templates tab or open the Builder tab, and add blocks from the left panel. The middle column shows how the message will look, and the right column holds the JSON. When it looks right, click Copy Payload and send that JSON with an incoming webhook or chat.postMessage. The builder needs no app and no paid plan.
We went through the current builder on 28 September and tested 16 broken payloads in it on 4 October; the screenshots below are from those sessions. We also make free Slack tools, including a markdown to Slack converter whose output drops into a section block.
What Block Kit Builder does
Block Kit is Slack's JSON format for app messages, modals and the App Home tab. It has no progress bar block, so a Slack progress bar is text that an app redraws with chat.update. Messages are a list of blocks: a header, sections of text, images, buttons, dividers, and newer blocks such as tables and cards. For the plan and task card blocks that agents use, our task card test shows which statuses each accepts and how they render. The "is working..." line an agent shows while it answers is not a block; it comes from a separate API call, which we tested in assistant.threads.setStatus vs agents.sessions.setStatus. The builder is a visual editor for that JSON. It does not send messages to a channel; your webhook or app does. It is also the only way to put a picture between two lines of one message, which the normal message box cannot do, as our test of inline images in Slack shows. Two blocks show media rather than text: a video block plays a YouTube embed or a player on a domain your app claims, and a file block shows a card for a remote or uploaded file.
How to use Slack Block Kit Builder, step by step
- Open the builder. Go to
app.slack.com/block-kit-builder. Pick your workspace in the menu at the top right if you are in more than one. - Start from a template. The Templates tab has groups such as Alerts, Approval, Notification, Onboarding, Poll and Rich Markdown. Click one to open it in the builder.
- Add or change blocks. On the Builder tab, the left panel lists block types: Agents, Markdown, Section, Actions, Condition, Input, Structure, Rich Text, Image, Card and Carousel, Callout, Table, Data Visualization, Container and Reference. Click one to add it. You can also type in the Payload panel on the right; the preview updates as you edit.
- Choose the surface. The first menu above the preview switches between Message Preview, Attachment Preview, Modal Preview and App Home Preview. A block that works in a modal may not work in a message, and the builder shows that. Long text behaves differently in the two message forms: Slack folds an attachment after 5 lines behind Show more and shows blocks in full, as our Show more test found. For the color bar on an attachment, our attachment color test lists which
colorvalues Slack keeps and which it drops. - Check Desktop and Mobile. The second menu switches the preview between Desktop and Mobile. Long button rows and wide images look different on a phone.
- Test the buttons. Click a button or pick a menu option in the preview, then open the Actions Preview tab. The three button styles and the errors for other colors are on our button style test. It shows the
block_actionspayload your app would receive. For select menus, including how long anexternal_selectoptions handler may take, see our select menu test. The payload a real click sends, and how many times itsresponse_urlworks, are in Slack interactivity payload, tested. To receive those clicks while the app runs on your laptop, you need a tunnel or Socket Mode; we compared ngrok, a Cloudflare tunnel and Socket Mode. - Copy the JSON. Click Copy Payload (the copy icon above the JSON). The trash icon, Clear Blocks, empties the canvas.

Example: a deploy message with buttons
We built this message in the builder. It has a header, a section with mrkdwn text and a link, a context line and two buttons:
{
"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"
}
]
}
]
}
Clicking Roll back in the preview and opening Actions Preview showed the payload an app gets, with "action_id": "rollback", "value": "rollback_v2140" and "style": "danger":
A button with a url opens that link. A button with only a value needs an app with interactivity turned on to receive the click; an incoming webhook alone cannot handle it. If that app never calls ack(), Slack puts a warning triangle next to the button, one of the cases in our Bolt error handling test. For up to 5 actions behind a "..." button instead of a row of buttons, use an overflow menu.
Send the payload with a webhook
An incoming webhook takes the same JSON. Add a top-level text: Slack uses it in notifications and for screen readers when the message has blocks.
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"
Paste the whole blocks array from Copy Payload in place of the one here. Setting up the webhook is in how to create a Slack webhook, and more request shapes and error codes are in Slack webhook curl example. With a bot token, send the same body to chat.postMessage with a channel field. If Slack answers invalid_blocks, our invalid_blocks test lists each limit and the error text it returns.
Never appear "away" on Slack again
Cloud-based. No downloads. Works 24/7 even when your laptop is off.
What Block Kit Builder does not catch
On 4 October we opened 16 payloads in the builder, each one a case we had already sent to Slack's API, and compared the builder's warnings with Slack's answer. The builder flagged duplicate action_id and block_id values, 51 blocks, an image URL it could not download, a section with no text or fields, and more than 10 fields. For a length error the red banner says only "failed to match all allowed schemas". The limit shows when you hover the red mark next to the line:
| Payload | Block Kit Builder | Slack's API |
|---|---|---|
| Header of 151 characters | Banner: failed to match all allowed schemas. Hover: must be less than 151 characters | invalid_blocks, must be less than 151 characters |
Duplicate action_id in one actions block | action_id "x" already exists | invalid_blocks |
| 51 blocks | no more than 50 items allowed | invalid_blocks |
| Markdown block of 12,001 characters | No warning | msg_too_long (a webhook answers HTTP 500) |
| Markdown block of 12,000 plus a 3,000-character section | No warning | chat.postMessage: msg_blocks_too_long |
The builder also sees only the blocks, not the top-level text or how a webhook answers. Our Block Kit checker takes the JSON from Copy Payload, shows the lines Slack returns on each send path, and its Open in Block Kit Builder button loads the fixed blocks back into the builder.
Share a Block Kit Builder link
The builder keeps the payload in the page address: after the # is the JSON, URL-encoded. Copy the address bar and anyone signed in to Slack sees the same message. You can also build such a link from code:
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)
We opened the link this script printed on 28 September, and the builder loaded the message from it.
Block Kit Builder tips
mrkdwn: *bold*, _italic_, <https://example.com|link text>. Standard markdown like **bold** and [text](url) stays literal there. The rules and the markdown block, which does read standard markdown, are in Slack Block Kit markdown. To convert text you already have, or to preview a single mrkdwn text, use the markdown to Slack converter.<@U0123ABCD> with a member ID; see how to mention a user in a Slack webhook.<!date^1790553600^{date_short} at {time}|fallback>; our Slack timestamp generator builds the string.FAQ
Is Slack Block Kit Builder free?
Yes. You need a Slack account to open it, but no app and no paid plan.
Can Block Kit Builder send a message to a channel?
No. It builds and previews the JSON. Send it with a webhook, chat.postMessage or a workflow; in C#, SlackNet can build the same blocks from typed classes, as in our Slack API in C# test.
How do I add a button in Block Kit Builder?
Add an Actions block from the left panel, or add a button element to a section as its accessory. Give it a url to open a link, or an action_id and value for your app to handle. When the app answers a click with Bolt's respond(), the reply replaces the message that holds the button unless you pass replace_original=False, as our say vs respond test found.
Can I use Block Kit Builder for modals and App Home?
Yes. Switch the surface menu above the preview to Modal Preview or App Home Preview. To open the modal from your app, call views.open within about 3 seconds of the click; our expired_trigger_id test measured the window.
Stop Jiggling Your Mouse.
Join hundreds of remote workers who never worry about their Slack status. Set it up once, stay green forever.
Related Articles
How to Mention a User in a Slack Webhook: <@ID>, @here and Groups
To mention someone in a Slack incoming webhook, put their member ID in angle brackets: <@U0123ABCD>. A plain @name stays text. @here is <!here>, @channel is <!channel>, and a user group is <!subteam^S0123ABCD>. Where to find the IDs, a lookup-by-email script, and what we measured.
Slack Webhook curl Example, Plus Python and Node.js
Send a Slack message with one curl command: POST a JSON body with a text field to your incoming webhook URL, and Slack answers ok. Tested examples for curl, jq, Block Kit, Python with retries and Node.js, how to escape quotes and new lines, and what 400 invalid_payload and 429 mean in code.
Slack private_metadata: Pass Data to a Modal (Tested Limit)
private_metadata is a hidden string on a modal view that Slack hands back in view_submission. We tested it on 18 November 2026: a JSON blob came back unchanged, and the limit is 3,000 characters, counted as characters, not bytes.