loading...

Beautiful, Blocky Slack Messages

nathanheffley profile image Nathan Heffley ・4 min read

Recently Slack released a new message format that apps can take advantage of called Block Kit. This new format allows apps and other software to send very rich messages through API calls or webhooks.

A Slack message styled to look like a search result displaying three hotels

An example of hotel search results as a message, one of Slack's official Block Kit example templates.

If you're interested in sending messages like this, you'll first have to set up a Slack app. You'll need to have an account and workspace you can use for developing an app. Once you have that all lined up, you'll need to visit https://api.slack.com/apps and press the "Create New App" button.

Name it whatever you want and select the workspace you'll use for testing. The quickest way to start sending messages is to set up a webhook, so click on "Incoming Webhooks" in the sidebar menu and toggle the switch to activate incoming webhooks.

Now at the bottom of the page you should see a button to add a new webhook to your workspace. Clicking on that will prompt you to select a channel and authorize the app. Since you should be able to trust that you won't abuse your own app, go ahead and pick whatever channel you want to send your test messages to and authorize yourself.

You'll be redirected back to the previous page, but now you'll see a webhook for the channel you just selected. Copy that URL because we're going to use it now to send a message!

To make sure your webhook is working, you can send yourself a simple message with the following curl command, just make sure to replace the webhook URL with the one you just copied.

curl -X POST -H 'Content-type: application/json' --data '{"text":"Hello, World!"}' https://hooks.slack.com/services/YOUR/WEBHOOK/HERE

Now, to send a block message, things start to get a little bit crazy. For the sake of simplicity we'll send a full block message with a curl command, but just know that this is a very simple message and I do not condone using curl as your main form of posting Slack messages.

curl -X POST -H 'Content-type: application/json' --data '{
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*<fakeLink.toUserProfiles.com|Iris / Zelda 1-1>*\nTuesday, January 21 4:00-4:30pm\nBuilding 2 - Havarti Cheese (3)\n2 guests"
            },
            "accessory": {
                "type": "image",
                "image_url": "https://api.slack.com/img/blocks/bkb_template_images/notifications.png",
                "alt_text": "calendar thumbnail"
            }
        }
    ]
}' https://hooks.slack.com/services/YOUR/WEBHOOK/HERE

If you type that into your terminal (you don't copy and paste random multi-line commands from the internet directly into your terminal, right?) you'll see a simplified version of another one of Slack's example templates. In this case, it's a simple meeting reminder message with a bit of information and a nice little graphic to let you know that it's a calendar event.

As for how these blocks actually work, let's go over what some of these bits are.

The entire JSON object in the data option is a message payload. Before blocks you would have to include something like a text key like in the first message example. Now with Blocks you can have just a blocks key which will be an array of the blocks you want to include in your message. Because it's an array, you can send as many blocks in one message as you would like. This is what allows for extremely rich blocks like in the image I had at the start of this post.

Within each block object you're required to have at the very least a type property. The most general type you can have is a section, which just means it's a generic type of block. You can also have image, context, actions, and divider type blocks, all of which have slightly different use cases.

In the case of our example block, we included some text in the text property. Text values are themselves an object, and can be either mrkdwn or plain_text. In this case we're using Markdown because the title of the meeting is a bold link. The text's text property is where the actual text goes.

Then finally, this section has a special extra bit called an accessory. An accessory can be an image, button, date picker, or a whole menu. In this case we added an image, specifically the image of a calendar icon.

A Slack message styled to look like a calendar event reminder

For a more in-depth dive on these rich message layouts, check out the official Slack documentation on creating rich message layouts!

Block Kit is pretty new, and I haven't seen as much support for it as I'd like to. Since my current framework of choice is Laravel, I tried finding out if there was an easy way to send Block messages. While there is an official package to send notifications to Slack, they've decided to not support Block Kit 😞

I've gone ahead and created a package that basically extends the official one, but with support for Block Kit included. If you use Laravel and are interested in taking advantage of this rich notification system, check out my package on GitHub!

GitHub logo nathanheffley / laravel-slack-blocks

An extension of the official `laravel/slack-notification-channel` package to add support for Slack Blocks.

Laravel Slack Blocks

This package is an extension of the official laravel/slack-notification-channel package.

Usage

Instead of requiring the official package, you should require this one instead.

composer require nathanheffley/laravel-slack-blocks

Because this package is built on top of the official one, you'll have all the functionality found in the official docs.

You can follow those instructions with the slight adjustment of requiring the classes from NathanHeffley\LaravelSlackBlocks instead of Illuminate\Notifications.

Everything supported in the base Illuminate Notifications classes is supported in these extended classes.

If you want to add a block to your Slack message, you need to add the block in an attachment.

use NathanHeffley\LaravelSlackBlocks\Messages\SlackMessage
//
public function toSlack($notifiable)
{
    return (new SlackMessage)
        ->attachment(function ($attachment) {
            $attachment->block(function ($block) {
                $block
                    ->type('section')
                    ->text([
                        'type' => 'mrkdwn'
                        'text' => '*Hello World!*',
                    ]);
            });
        });
}

To see all the possible fields you can add to a block, check out the…

Posted on by:

nathanheffley profile

Nathan Heffley

@nathanheffley

Full-stack developer most often found working on something Laravel related.

Discussion

markdown guide