Back to Blog
Guide

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.

Slack Green Team
September 28, 2026
November 13, 2026
7 min read
Share:
slack
block kit
api
webhooks

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.
  • Block Kit Builder Templates tab: categories on the left and message previews such as Approval

  • 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 color values 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_actions payload your app would receive. For select menus, including how long an external_select options handler may take, see our select menu test. The payload a real click sends, and how many times its response_url works, 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:

    Slack Block Kit Builder with a deploy message: header, section, context and two buttons, with the JSON payload on the right
    {
      "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":

    Block Kit Builder Actions Preview after clicking Roll back: block_actions payload with action_id rollback and value rollback_v2140

    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:

Block Kit Builder with a 151-character header: the banner says failed to match all allowed schemas, the hover on line 7 says must be less than 151 characters
PayloadBlock Kit BuilderSlack's API
Header of 151 charactersBanner: failed to match all allowed schemas. Hover: must be less than 151 charactersinvalid_blocks, must be less than 151 characters
Duplicate action_id in one actions blockaction_id "x" already existsinvalid_blocks
51 blocksno more than 50 items allowedinvalid_blocks
Markdown block of 12,001 charactersNo warningmsg_too_long (a webhook answers HTTP 500)
Markdown block of 12,000 plus a 3,000-character sectionNo warningchat.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.

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

  • • Text formatting. Section text uses Slack's 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.
  • • Mentions. Use <@U0123ABCD> with a member ID; see how to mention a user in a Slack webhook.
  • • Dates in the reader's time zone. <!date^1790553600^{date_short} at {time}|fallback>; our Slack timestamp generator builds the string.
  • • Limits. Slack caps the number of blocks per message and the length of each text. See Slack message character limit.
  • • Tables. The left panel now has a Table block; for plain text messages, see how to make a table in Slack.
  • • Charts. The Data Visualization entry previews line, bar, area and pie charts. Slack allows 2 per message; the limits we hit are in Slack Block Kit charts.
  • 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.

    Always Active

    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

    Guide

    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 Green Team
    Guide

    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 Green Team
    Developers

    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.

    Slack Green Team