Overview

Block Kit is the JSON format for every message your bot sends. It is the same format on all three paths: webhook response, response URL, and API key.

The standard shape

{
  "block_kit_version": "1",
  "messages": [
    {
      "mid": "reply-1",
      "metadata": { "order_id": "4821" },
      "blocks": [
        { "type": "text", "text": "Your order **#4821** has shipped!" },
        {
          "type": "button_group",
          "buttons": [
            { "action_id": "track", "label": "Track package", "value": "4821" }
          ]
        }
      ]
    }
  ]
}

block_kit_version

string

Currently "1". Optional — leave it out and you get "1". Any other value is rejected with BLOCK_KIT_VERSION_UNSUPPORTED.

messages

array

required

1–10 messages. Each one becomes its own chat bubble group. That lets one reply arrive as a few short bubbles instead of one wall of text.

Show message

blocks

array

required

1–25 blocks, drawn top to bottom. See Block types.

mid

string

Your own id for this message. Must match ^[a-zA-Z0-9_.:-]{1,64}$. Send it again to update the message instead of posting a copy.

metadata

object

Any JSON you like, up to 2 KB. Never shown to anyone — but sent back word for word in every interaction event from this message. Use it to carry state through a button click without a database.

Every block can also have a block_id (same character rules as mid). Leave it out and we make one, like blk_a1b2c3d4e5f6.

Block types

Ten block types, each with its own page.

Type	Purpose
`text`	Markdown text
`image`	A picture
`file`	A download card
`button_group`	Up to 5 buttons
`form`	Up to 10 input fields
`card`	Image, title, text, and buttons together
`divider`	A horizontal line
`status`	Progress and state
`page_preview`	A link card to a hosted Page
`page`	Publish HTML as a Page (write-only)

Shortcuts

You rarely need the full shape. We accept all of these and convert them into the standard shape for you. Your first try usually just works.

"Order refunded."

{ "text": "Order refunded." }

{
  "text": "Anything else?",
  "buttons": ["Yes please", "No thanks"]
}

{
  "blocks": [{ "type": "text", "text": "Order refunded." }]
}

{ "type": "text", "text": "Order refunded." }

[
  { "text": "First bubble" },
  { "text": "Second bubble" }
]

What we clean up for you

You send	We store
A plain string where a block should be	A `text` block
`markdown` instead of `text`	`text` (they mean the same; `text` wins if you send both)
`"Yes please"` in `buttons`	`{ "action_id": "yes_please", "label": "Yes please", "value": "Yes please" }`
`"Billing"` in a select’s `options`	`{ "label": "Billing", "value": "Billing" }`
A button with no `action_id`	An `action_id` made from its label. Repeats get `_2`, `_3`
A number or true/false in a text field	The same value as a string (`42` becomes `"42"`)
`null` in an optional field	The field is removed
A `status` block’s `progress` of `140`	`100` — pulled back into range
Unknown fields	Removed, and noted in your delivery log

We trim spaces from the ends of label, title, name, action_id, and submit_label. Spaces inside text are kept, because markdown needs them.

Empty replies are fine too. An empty body or {} from a webhook means “got it, no message” — the typing dots stay on while you finish the work. But posting an empty body to a response_url is an error (422 EMPTY_BODY).

Markdown

Markdown works in text blocks, card.text, status.detail, and form help. Supported: bold, italic, strikethrough, inline code, code blocks, links, autolinks, ordered and unordered lists, quotes, headings, tables, and line breaks. A single newline makes a line break — Slack-style, not strict CommonMark. That is what most people expect. Not supported:

Raw HTML. It is stripped before drawing, never run.
Image syntax ![alt](url). It shows as a plain link — use the image block instead.
Footnotes and task-list checkboxes.

Links can only use https: or mailto:. Anything else — including javascript: and data: — shows as plain text. Every link opens in a new tab.

Unicode emoji pass through untouched. :shortcode: emoji are not translated.

Versions

block_kit_version is a string. New things are added inside "1" — new block types, new optional fields, higher limits. They will not break you. Unknown block types do not crash anything. They show as a placeholder in the app and are skipped on public pages. An old widget will not break when a new block ships.

Every block type

All ten, with full schemas.

Limits and errors

Every limit, and what happens when you cross one.

Get started

Sending messages

Block Kit

Receiving events

No-code platforms

The standard shape

Block types

Shortcuts

What we clean up for you

Markdown

Versions

Next

Every block type

Limits and errors

​The standard shape

​Block types

​Shortcuts

​What we clean up for you

​Markdown

​Versions

​Next

Every block type

Limits and errors

The standard shape

Block types

Shortcuts

What we clean up for you

Markdown

Versions

Next