Slack app Block Kit migration guide — Part 1
Introduction
Slack platform introduced the Block Kit API about a half a year ago. Raidboss app had been in development for a while but was still in beta.
You know that feeling when you are in the middle of development and the library publishes a release or a 3rd party service changes their API; it’s always a dilemma — jump onto the new version right now (by postponing the overall release) or keep using the current solution (while accumulating technical debt).
Bless the Slack platform team for keeping the previous version available, at least for now, and allowing developers to publish new apps built with the Block Kit predecessor — message attachments.
In our efforts, we decided to explore the capabilities of the new Block Kit shortly after public release.
Changes overview
For those who built their app before the appearance of Block Kit (using message attachments), let’s quickly look at what actually has been changed.
Visual perspective
The main benefit of switching to Block Kit is a powerful set of new visual components.
In other words, now you can build a more sophisticated message or make your messages more clear and readable.
Let’s check what we have got item by item.
Section instead of Attachment
Section is a type of Block which is the most similar to old Attachment.
The difference is that the Section does not include a colored bar on the left side.
This makes each Section appear more independent, while old Attachments looked like they were “in the context” (because of the color bar indent) of the main text message.
We are still able to display some sort of fields — formatted text divided into 2 columns. This replaces the old `fields` within the Attachment object but is not limited to label-value format (this means more freedom — we can decide to make it bold or multiline).
What I like in this Section Block is an `accessory` field. Previously we had a limited set of extra elements within each Attachment and each of them had a strictly designated position in the visual layout of the message.
Thumb is on the right, image and actions are at the bottom.
Section is a more structured component. The goal of the `accessory` field within Section is to serve as a placeholder for one of the specific elements precisely in the top right corner of the Section. These specific elements are called Block Elements and existing elements are an image, button, select menu, overflow menu, and date picker.
While all old types of elements (image, footer, author and other) have been moved to other Block types (see the description of `Image`, `Actions` and `Context` later in this article), what does it mean for us? Instead of ‘attaching’ visual pieces of data to something (the main text of the message) we are free to build the layout of our message with Blocks. We believe this is the main conceptual shift of the Block Kit feature.
Divider
This element is purely for improving visual perception of your message: a horizontal rule without any functionality.
Despite the simplicity, it is a very powerful element in designing messages.
Image
Image is an image, as always. But now we are free to put an image at any level of our stack of Blocks as many times as we want and without any extra effort to define this kind of Block.
Actions
In addition, to become an independent Block there are new types of actions: overflow menu and date picker.
Using the Overflow menu, it is easy to put accents on main actions by hiding the less important options inside a dropdown.
The appearance of the ability to insert a formatted date was the most highly demanded feature in the past and is useful for almost any Slack app. We believe that it will soon be possible to put the date picker in the dialogs.
Context
This type of Block is similar to the old `footer` field of Attachment, which was grayed and a bit smaller piece of text. But now it is like a combination of multiple images and text units in a row.
Technical perspective
Not much is changed from a high-level point of view. Previously we had an `attachments` field at the top level of the message’s JSON payload with an array of Attachment objects (each Attachment represents one piece of the resulting message). With Block Kit, we have to use the top-level `blocks` field of the message. Obviously, this new field contains an array of Block objects.
Conceptually, there is just one detail more. While Attachment objects are all of the same kind, each Block has its own type (`Section`, `Divider`, `Image`, `Actions`, `Context`) with its own set of allowed fields.
Internally, Block has the list of fields which are different from Attachment. See the official spec for details.
Secondary attachments
An interesting fact is that it’s still possible to use the `attachments` field within the same message with `blocks`. This old `attachments` field can contain another `blocks` field with an array of Blocks.
This is interpreted as a secondary set of data and designed to display less important information. It looks like a cool feature, but for some reason it’s marked as legacy.
Conclusion
We really liked how the Slack platform is evolving. All of the changes to the message layout are concise and practical. For the Slack-first app, it’s essential to be up to date with the recent changes and apply them appropriately.
Most probably, you already had a look at the Block Kit builder tool to play with new Blocks.
As a small tip for the design stage of your messages, there is a button to test your experimental message before development. You can send a test message to any channel or directly to the user (undocumented trick) by specifying channel ID (or a name like ‘general’) or user ID. Both can be found in the URL of the web version of Slack by opening channel or direct user conversation.
In the next part of the article, we will cover our actual strategy of how we are migrating the Raidboss app from Attachments to Block Kit by leveraging the maximum power of Blocks.
