Slack Block Kit Builder: How to Use It, Templates, Payload

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. 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 builder is a visual editor for that JSON. It does not send messages to a channel; your webhook or app does.

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.
• 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.
• 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.

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.

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:

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

• 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.

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.

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.