Welcome to slackblocks!

slackblocks builds Slack messages with the Block Kit API in Python and TypeScript — without writing JSON by hand.

It exists because Block Kit JSON is verbose, easy to get subtly wrong, and unpleasant to maintain in source control. slackblocks gives you:

• Typed, idiomatic APIs for Python and TypeScript.
• Validation as you build — character limits, required fields, mutually-exclusive options, and element-type restrictions are enforced at construction time, so you find out before hitting Slack's API.
• Drop-in compatibility with the official Slack SDKs and their plain JSON payloads.
• Zero runtime dependencies.

Quick Start

Ready to build your first message? The Quick Start guide takes you from installation to a validated Slack payload using the language selected in the top navigation.

Components

The Slack Block Kit API defines several resource types (all defined in JSON) that work together to build block-based messages.

The Python package mirrors that hierarchy with classes.

Objects

Objects (e.g. Text, Option, Confirm) are the lowest-level primitives — small composable pieces that populate Elements and Blocks.

For convenience, PlainText and Markdown are thin subclasses of Text that you can use anywhere a Text is expected — PlainText("Hi", emoji=True) reads more naturally than Text("Hi", type_=TextType.PLAINTEXT, emoji=True).

Elements

Elements are typically interactive UI controls that go inside blocks. The CheckboxGroup element, for instance, takes one or more Option items and presents a checkbox menu.

Blocks

Blocks are the core visual unit of a message. Different block classes produce different UI:

• SectionBlock — a chunk of markdown text, optionally with an accessory element.
• HeaderBlock — a large bold title.
• DividerBlock — a visual separator (like an HTML <hr>).
• MarkdownBlock — GitHub-flavored Markdown (Slack 2024+; richer formatting than mrkdwn).
• RichTextBlock — formatted text with inline styling, lists, code blocks, and quotes.
• ActionsBlock — a row of interactive elements like buttons or menus.
• AlertBlock — a severity-labelled notice for a modal.
• CardBlock and CarouselBlock — compact linked content, individually or in a scrolling collection.
• ContainerBlock — a titled group of related child blocks.
• ContextActionsBlock — feedback and icon controls beside contextual content.
• DataTableBlock and DataVisualizationBlock — structured data as a table or chart.
• PlanBlock and TaskCardBlock — plans, task state, rich output, and sources.
• VideoBlock — embed a video from a Slack-supported provider.
• ImageBlock, ContextBlock, InputBlock, FileBlock, TableBlock.

See Using Blocks for examples of all block types side-by-side with their JSON output and Slack rendering.

Messages

Messages are a convenience wrapper around blocks that can be unpacked directly into the Slack SDK's chat_postMessage (and friends).

• Message — a normal channel message.
• WebhookMessage — for incoming webhooks.
• MessageResponse — replies to slash commands and interactions.

Views

Views are an alternative usage of blocks that build custom UI surfaces in Slack — modal dialogs and the App Home tab — typically used by interactive Slack apps.

Utilities

• block_kit_builder_url(payload, team_id=None) — turn any block, list of blocks, message, or view into a Block Kit Builder URL for browser-based preview.
• Block.from_dict(data) — parse a Slack-shaped block payload back into a slackblocks object. Per-class from_dict parsers are also available on every composition object.

Guides

• Installation
• Using Blocks
• Sending Messages
• Recipe Book — complete end-to-end recipes for common message patterns.
• Troubleshooting & FAQ
• Migrating from 1.x to 2.x — upgrade guide for 1.x users.
• Contributing — developing and contributing to slackblocks itself.