Migrate your legacy message compositions to blocks
In early 2019 we introduced a new way of composing messages, by using blocks to create rich and interactive layouts. Slack apps designed and built before then may have used features such as attachments which are now considered outmoded.
These older features will continue to work, but apps using them will miss out on the new layout and interactivity features blocks provide.
This guide is intended for developers of existing Slack apps that are using outmoded composition features. It will provide information on the best ways to transform your messages to block layouts and introduce new ways of thinking about message composition in the era of blocks. We will also show you the newer blocks and elements that can be used to directly replace outmoded visual components such as attachments.
Planning your upgrade
In many cases, message layouts directly map to an exact block equivalent. If your app sends messages with text and some buttons, this strategy may work best for your app:
This case may not warrant any more work after you switch to blocks.
We strongly recommend, however, that all developers of Slack apps use this opportunity to completely rethink their message compositions, and take advantage of the exciting new features and possibilities that have been introduced.
Consider these basic guidelines when migrating to block-based message composition:
Use new elements to simplify messages
New block elements such as overflow menus or date pickers offer the opportunity to clean up message complexity. Keep the focus of a message on what users are trying to do right there and then, and de-emphasize interactive actions that are less important.
Here's an example message that might have been directly ported from an older, attachment-based version:
With the help of the new overflow menu, this message could instead be simplified and focused:
Use new elements to add functionality
While switching to blocks can let you hide previously visible and messy elements from view, you can also use new features like the overflow menu to introduce brand new functionality to your app's messages.
Where before you might have cautiously avoided cluttering your messages with secondary actions that were nevertheless useful, now you can add them while keeping things clean.
Consider mobile layouts of blocks and elements
The replacement block for your outmoded visual element might create an identical layout on desktop clients, but make sure the mobile view still looks good. Some blocks can have very different layouts on desktop clients compared to mobile:
Free your messages from layout constraints
If you've used attachments, you'll know that they conform to a very strict order of visual elements. You can't change where the author_name field renders in a message, for example. This leaves designers of Slack apps constrained in terms of the range of possibilities for message layouts.
Apps that switch to using layout blocks can choose from any of the available blocks and elements, stacking them in whatever order is desired. Blocks can also be repeated within the same message, giving a designer a huge amount more composition flexibility. For example, that author_name field mentioned above becomes a context block that could be placed anywhere in the message, and contain more than just an author name.
Prototype with Block Kit Builder
Seeing is believing. Block Kit Builder is a visual prototyping tool that lets you preview message composition without writing any code.
Use it to prototype your new message designs, to check the validity of the blocks JSON that you're publishing, and to examine sample interaction payloads.
Switching to block layouts
Now that you've planned your app's transition to using blocks, you probably have some questions about the nitty gritty. Following is a list of important information to understand the changing paradigms compared to the older ways of composing messages.
Finding equivalents for older visual elements
Nearly every older visual element has a direct equivalent in blocks or block elements. If you were using attachments, you can find a list of block alternatives for each visual component in our attachment fields reference guide.
There is one exception, and that's the color parameter, which currently does not have a block alternative. If you are strongly attached (πΊ) to the color bar, use the blocks parameter within an attachment.
This will let you place newer blocks inside of an attachment, but bear in mind the advice above and use the opportunity to rethink your message composition. Users will increasingly associate attachments with less-important secondary content because they have a lower visual hierarchy compared to blocks.
There are a few more things to watch out for if you're an old hand at pre-block message composition.
Include text in objects rather than as fields
Instead of the older, awkward way of defining text - as a flat field with a separate mrkdwn_in array to determine the formatting method - within blocks there is a new, saner way to structure text.
Using text objects you can define the actual text content, as well as the formatting method (mrkdwn or plain_text) in the same place. Read the reference guide for text objects to see an example and full details.
Watch out for changes to field limits
A lot of limits - for things like the maximum length of text fields, or the number of elements that can be included in a block - will be different from what you may be used to. Check out the block reference guides for full details of any limits applied to particular fields.
Prepare for the new structure of interaction payloads
If you were using any of the outmoded versions of interactive components, such as buttons or menus, your app will be built to handle the specific interaction payload from those outmoded components.
While the structure of the interaction payload is largely the same for the newer interactive components, you should prepare your app for the new structure, accommodating small changes like the new type of block_actions that will be included. Our reference guide contains an outline of this new interaction payload structure.
This payload will also include new block_id and action_id fields, as described below.
Use block_id and action_id instead of callback_id
In the past, including a callback_id when publishing a message would allow you to pass a unique identifier for a group of buttons in an interactive message attachment. This callback_id was sent with the interaction payload when someone clicked one of the buttons.
With interactive components in blocks, there are two new fields that can replicate this same functionality, block_id and action_id. Both (or one or none) of these fields can be specified when you're composing a message, and they'll be included with the interaction payload sent to your app.
block_id is specified in blocks. It can be used to identify the parent block of the source interactive component used in an interaction. If you don't specify a block_id, one will be automatically generated for the block, and included in interaction payloads.
action_id is specified in interactive components. It can be used to identify the source interactive component used in an interaction. If you don't specify an action_id, one will be automatically generated for the element, and included in interaction payloads.
In addition, the value field for options will continue to identify which item within an interactive component was chosen (for example the chosen option within a select menu).
Specify fallback text for message notifications
Unless you're sending messages that only contain plain text, you'll need to provide fallback text when publishing a message. This fallback text will specify what should appear in any notifications prompted by the publishing of the message.
Previously there was a fallback field defined within the attachment object to define this fallback text.
When you're using blocks in a message, however, you specify fallback text by using the top-level text field within the payload your app is sending to publish the message. The text field won't render in messages in Slack clients as long as blocks is also provided, but it will show up as the fallback text in notifications.
If you're not including the blocks field, the top-level text field will continue to render in messages as normal.
Use only response_url to publish messages in response to interactions
When an interaction occurs, apps receive an interaction payload in an HTTP request.
In the past, apps could respond directly to this HTTP request to publish a new message. The response_url from the interaction payload could then be used to publish any subsequent messages.
With blocks, it is not possible to publish a new message by responding directly to the HTTP request. You will always need to use the response_url for this purpose. The HTTP response may now only be used to send an HTTP 200 acknowledgement response.
Read our guide to responding to interactions to find out more information about acknowledgement responses, and how to use the response_url to publish, delete, and update messages.