Blockkit

2.1.3 · active · verified Thu Apr 16

Blockkit is a Python library for building user interfaces for Slack apps. It provides a fluent API with type hints and validation, allowing developers to compose Slack's Block Kit elements using Python classes, which reduces boilerplate and improves maintainability. The library is currently at version 2.1.3 and is actively maintained with frequent releases.

Common errors

```
slack.errors.SlackApiError: The request to Slack API Failed. The server responded with: {'ok': False, 'error': 'invalid_blocks_format'}
```
cause The generated Block Kit JSON structure is malformed or does not adhere to Slack's API specifications (e.g., missing required fields, incorrect types, invalid nesting).

fix Ensure all Blockkit components are correctly instantiated and chained according to the library's fluent API. The `.build()` method performs validation; check its output for detailed errors. Use Block Kit Builder (api.slack.com/tools/block-kit-builder) to prototype and validate your structure.
```
Not receiving block_action payload when interacting with a Slack Block Kit modal/message
```
cause The interactive elements (e.g., buttons) are not correctly configured within an `ActionsBlock` or `InputBlock` with `dispatch_action: true`, or the Slack App's 'Request URL' for interactivity is not set up or reachable.

fix Verify that your Slack App's 'Interactivity & Shortcuts' 'Request URL' is correctly set and your server is publicly accessible. Also, ensure interactive elements in your Blockkit structure are properly nested within `Actions` blocks or `Input` blocks configured to dispatch actions.

Warnings

breaking Version 2.0.0 was a complete rewrite of the library with a new fluent API and zero dependencies. Code written for versions prior to 2.0.0 will not be compatible.
Fix: Rewrite Block Kit UI construction using the new fluent API. Refer to the official documentation for migration guidance and new syntax.
gotcha When using interactive components (e.g., buttons, select menus) within Blockkit, ensure your Slack App's 'Interactivity & Shortcuts' feature has a properly configured 'Request URL'. Without this, Slack cannot send interaction payloads (like `block_action`) to your application.
Fix: Configure the 'Request URL' in your Slack App settings (api.slack.com/apps) under 'Interactivity & Shortcuts'. Ensure your server endpoint correctly receives and processes Slack's `POST` requests.
gotcha Slack's 'mrkdwn' formatting has subtle differences from standard Markdown. While Blockkit aims to handle common cases automatically, be aware of specific syntax requirements for elements like links (`<url|text>`) or bold (`*text*`).
Fix: Refer to Slack's 'Formatting text for app surfaces' documentation for exact 'mrkdwn' syntax. Blockkit's automatic detection usually works, but manual review for complex formatting may be needed.

Install

pip install blockkit Install latest version

Imports

Modal
```
from blockkit import Modal
```
Section
```
from blockkit import Section
```
Message
```
from blockkit import Message
```
Button
```
from blockkit import Button
```
Confirm
```
from blockkit import Confirm
```

Quickstart

This example constructs a Slack message with an approval request, including a button with a confirmation dialog. The `.build()` method validates the Block Kit structure, ensuring compliance with Slack's API specifications. The generated `message` object can be directly passed to the `blocks` parameter of `slack_sdk.WebClient.chat_postMessage`.

from blockkit import Message, Section, Button, Confirm

message = (
    Message()
    .add_block(Section("Please approve *Alice's* expense report for $42")) # Markdown detected automatically
    .accessory(
        Button("Approve")
        .action_id("approve_button")
        .style(Button.PRIMARY)
        .confirm(
            Confirm()
            .title("Are you sure?")
            .text("This action cannot be undone")
            .confirm("Yes, approve")
            .deny("Cancel")
        )
    )
    .thread_ts(os.environ.get('SLACK_THREAD_TS', '1234567890')) # Converts types automatically
    .build() # Validates everything: types, lengths, required fields
)

# To send this message via Slack's WebClient, you would typically do:
# from slack_sdk import WebClient
# client = WebClient(token=os.environ.get("SLACK_BOT_TOKEN"))
# response = client.chat_postMessage(
#     channel="C12345",
#     blocks=message # Blockkit objects are directly serializable to JSON dicts expected by Slack SDK
# )

print(message)

view raw JSON →