 |
VOOZH | about |
|
VOOZH | about |
This page documents the SlackMessage class, which is used to construct modern Slack notifications using Block Kit. The SlackMessage provides a fluent interface for building rich, interactive messages with blocks, buttons, images, and other UI components.
For information about the legacy attachment-based Slack message format, see Legacy Slack Attachments. For detailed documentation of individual Block Kit components (blocks, elements, composites), see Slack Block Kit. For information about how Slack messages are routed and delivered, see Slack Channels.
The SlackMessage class serves as the primary message builder for Slack notifications. It converts notification content into the JSON payload format expected by Slack's API endpoints.
Class Location and Structure
Sources: src/Slack/SlackMessage.php1-336
The SlackMessage class manages several categories of properties that control message appearance and behavior:
| Property Category | Properties | Purpose |
|---|---|---|
| Content | text, blocks | Message content (text fallback and Block Kit blocks) |
| Targeting | channel, threadTs, broadcastReply | Where the message is sent |
| Appearance | username, icon, image | Bot identity customization |
| Behavior | mrkdwn, unfurlLinks, unfurlMedia | Content rendering options |
| Advanced | metaData | Structured metadata for app functionality |
Sources: src/Slack/SlackMessage.php26-86
The to() method specifies which Slack channel receives the message:
The channel value is stored in the channel property and included in the final JSON payload.
Sources: src/Slack/SlackMessage.php90-95
The text() method sets the message's text content, which serves as:
At least one of text or blocks must be present, or toArray() will throw a LogicException.
Sources: src/Slack/SlackMessage.php100-105 src/Slack/SlackMessage.php298-300
The SlackMessage class provides convenience methods for adding Block Kit blocks. Each method accepts a closure that receives a block instance for configuration:
| Method | Block Type | Purpose |
|---|---|---|
actionsBlock() | ActionsBlock | Interactive buttons and selects |
contextBlock() | ContextBlock | Contextual information (text + images) |
dividerBlock() | DividerBlock | Visual separator line |
headerBlock() | HeaderBlock | Large heading text |
imageBlock() | ImageBlock | Full-width image display |
sectionBlock() | SectionBlock | Text content with optional accessory |
Example Usage:
The blocks are stored in the blocks array property. When converted to an array, each block that implements BlockContract has its toArray() method called.
Sources: src/Slack/SlackMessage.php107-180 src/Slack/SlackMessage.php308
The username() method customizes the bot name displayed in Slack:
This overrides the default bot name configured in the Slack app settings.
Sources: src/Slack/SlackMessage.php246-252
Two methods control the bot's avatar:
Emoji Icon:
Image Icon:
Note that these methods are mutually exclusive. Setting an emoji clears the image, and vice versa.
Sources: src/Slack/SlackMessage.php185-202
By default, Slack parses markdown in message text. This can be disabled:
This sets the mrkdwn property to false, which is included in the JSON payload.
Sources: src/Slack/SlackMessage.php217-222
Control how Slack handles links in the message:
Unfurl Links:
Unfurl Media:
These correspond to Slack's unfurl_links and unfurl_media API parameters.
Sources: src/Slack/SlackMessage.php225-242
To send a message as a thread reply, provide the parent message's timestamp:
The threadTs property identifies the parent message in Slack's threading system.
When replying to a thread, optionally broadcast a reference to the parent channel:
This shows a "replied in thread" notification in the main channel.
Sources: src/Slack/SlackMessage.php257-272
The metadata() method attaches structured metadata to messages:
This creates an EventMetadata instance with an event type and payload. The metadata can be used by Slack apps for custom functionality like filtering, routing, or triggering workflows.
The metadata is serialized to JSON using the metadata field in the Slack API.
Sources: src/Slack/SlackMessage.php207-212 src/Slack/SlackMessage.php311
The usingBlockKitTemplate() method imports a complete Block Kit JSON structure:
Requirements:
JsonException if not)blocks key (throws LogicException if missing)This is useful for:
Sources: src/Slack/SlackMessage.php279-291
The dd() method provides debugging assistance:
When called without the raw parameter, it generates a URL to Slack's Block Kit Builder with the message pre-loaded. This allows visual inspection and editing of the message structure.
The generated URL format:
https://app.slack.com/block-kit-builder#<urlencoded-json>
Sources: src/Slack/SlackMessage.php328-335
The toArray() method enforces that messages contain either text or blocks:
This validation occurs when the message is converted to its JSON array representation.
Slack limits messages to 50 blocks maximum:
This is a Slack API limitation enforced by the toArray() method.
Sources: src/Slack/SlackMessage.php298-304
The toArray() method converts the SlackMessage to the array structure expected by Slack's API:
Field Mapping:
| SlackMessage Property | JSON Field | Notes |
|---|---|---|
channel | channel | Always included |
text | text | Optional |
blocks | blocks | Each block converted via toArray() |
icon | icon_emoji | Optional |
image | icon_url | Optional |
metaData | metadata | Converted via EventMetadata::toArray() |
mrkdwn | mrkdwn | Optional |
threadTs | thread_ts | Optional |
broadcastReply | reply_broadcast | Optional |
unfurlLinks | unfurl_links | Optional |
unfurlMedia | unfurl_media | Optional |
username | username | Optional |
Null values are filtered out before the final array is returned, ensuring only explicitly set values are included in the API payload.
Sources: src/Slack/SlackMessage.php296-323
The SlackMessage integrates with the notification system through the notification's toSlack() method:
The notification's toSlack() method constructs and returns a SlackMessage instance. The channel then converts it to an array and sends it to the appropriate Slack endpoint (Web API or Webhook).
Sources: src/Slack/SlackMessage.php21-336
Complete example showing common features:
Sources: src/Slack/SlackMessage.php1-336
Refresh this wiki