Slack Block Kit

Purpose and Scope

This document provides a comprehensive guide to building rich Slack messages using Block Kit components within the hypervel/notifications package. Block Kit is Slack's modern UI framework that enables interactive, structured messages with buttons, images, text formatting, and contextual elements.

This page covers the architecture and composition patterns of Block Kit. For general Slack message construction, see Slack Messages. For the legacy attachment-based format, see Legacy Slack Attachments. Detailed references for specific components are available in Block Kit Contracts, Block Types, and Elements and Composites.

Block Kit Architecture

Block Kit follows a three-layer architecture that composes into rich message structures. Each layer serves a distinct purpose in the message hierarchy:

Three-Layer Component System

Sources: Architecture derived from Diagram 3 in system overview

Layer	Purpose	Examples	Contains
Blocks	Top-level structural containers	ActionsBlock, SectionBlock, HeaderBlock	Elements and text objects
Elements	Interactive or visual components	ButtonElement, ImageElement, TextObject	Composite objects (optional)
Composites	Configuration objects	ConfirmObject, PlainTextOnlyTextObject	Primitive data

Contract System

All Block Kit components implement contract interfaces that extend Hyperf\Contract\Arrayable, enabling serialization to the array format required by Slack's API.

Sources: src/Contracts/Slack/BlockContract.php1-12 src/Contracts/Slack/ElementContract.php1-12 src/Contracts/Slack/ObjectContract.php1-12

Contract Interfaces

Contract	Location	Purpose
BlockContract	src/Contracts/Slack/BlockContract.php9	Marks top-level block components
ElementContract	src/Contracts/Slack/ElementContract.php9	Marks interactive/visual elements
ObjectContract	src/Contracts/Slack/ObjectContract.php9	Marks composite configuration objects

Each contract requires implementing toArray(): array, which serializes the component into Slack's JSON format. The contracts provide no additional methods beyond Arrayable, serving primarily as type markers for the component hierarchy.

Sources: src/Contracts/Slack/BlockContract.php1-12 src/Contracts/Slack/ElementContract.php1-12 src/Contracts/Slack/ObjectContract.php1-12

Component Composition Pattern

Block Kit components compose hierarchically, with blocks at the top containing elements, which may contain composite objects. This composition pattern enables building complex interactive messages from simple, reusable components.

Message Assembly Flow

Sources: Architecture derived from Diagram 3 in system overview

The composition follows this pattern:

1. Notification method (toSlack()) creates a SlackMessage instance
2. SlackMessage accumulates blocks via method chaining or array assignment
3. Blocks are instantiated with their required elements/text objects
4. Elements may include composite objects for additional configuration
5. Serialization occurs when the message is sent, calling toArray() recursively

Component Categories

The package provides comprehensive Block Kit support across all three layers:

Available Block Types

Block Type	Class Name	Purpose	Key Features
Actions	ActionsBlock	Container for interactive elements	Holds buttons, selects, menus
Section	SectionBlock	Text content with optional accessory	Main content block, supports markdown
Header	HeaderBlock	Large heading text	Plain text only, prominent display
Image	ImageBlock	Standalone image display	Full-width image with optional title
Context	ContextBlock	Small supplementary information	Multiple text/image elements
Divider	DividerBlock	Visual separator line	No configuration needed

Sources: Derived from Diagram 3 in system overview

Available Elements

Element Type	Class Name	Used In	Interactive
Button	ButtonElement	Actions, Section accessory	Yes
Image	ImageElement	Section accessory, Context	No
Text	TextObject	Section, Context, Header	No

Sources: Derived from Diagram 3 in system overview

Available Composite Objects

Object Type	Class Name	Purpose
Confirm	ConfirmObject	Confirmation dialog for destructive actions
Plain Text	PlainTextOnlyTextObject	Plain text wrapper with emoji flag

Sources: Derived from Diagram 3 in system overview

Serialization to Slack API Format

All Block Kit components implement the Arrayable contract, enabling seamless serialization to Slack's required JSON structure. When a notification is sent through the Slack channel, the serialization chain executes:

Sources: Architecture derived from Diagrams 1 and 2 in system overview

Serialization Chain

1. SlackMessage::toArray() initiates serialization
2. Each block's toArray() method serializes block-specific fields
3. Nested elements recursively serialize through their toArray() methods
4. Composite objects serialize to their configuration structures
5. The resulting nested array structure matches Slack's JSON schema

This recursive serialization pattern ensures type safety at composition time while producing the flat array structure Slack's API expects.

Sources: src/Contracts/Slack/BlockContract.php7-9 src/Contracts/Slack/ElementContract.php7-9 src/Contracts/Slack/ObjectContract.php7-9

Integration with SlackMessage

Block Kit components integrate with the SlackMessage class, which serves as the container for all blocks. The SlackMessage class manages the blocks array and handles serialization to Slack's payload format.

From the architecture diagrams, we see that SlackMessage (importance 10.13) routes through SlackNotificationRouterChannel to either SlackWebApiChannel or SlackWebhookChannel. Both channels accept the serialized block structure as part of the message payload.

Sources: Diagram 3 in system overview

Next Steps

For detailed information on specific Block Kit components:

• Block Kit Contracts - Detailed contract interface documentation
• Block Types - Complete reference for all block implementations
• Elements and Composites - Reference for elements and composite objects

For understanding how Block Kit messages are sent:

• Slack Messages - Message construction and configuration
• Slack Routing - How messages route to Web API or Webhooks
• Slack Web API Channel - Delivery through chat.postMessage

Sources: Table of contents and Diagram 1 in system overview