In early 2019 we introduced a new way of composing messages, by using blocks to create rich layouts and enable interactivity. Slack apps designed and built before then may have used features such as attachments which are now considered outmoded.
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
- Switching to block layouts
- Finding equivalents for older visual elements
- Include text in objects rather than as simple fields
- Watch out for changes to field limits
- Prepare for the new structure of interaction payloads
- Specify fallback text for message notifications
- Use only
response_urlto publish messages in response to interactions
In many cases, message layouts directly map to an exact block equivalent. If your app sends messages with simple text and some buttons, this strategy may work best for your app:
In this case, moving to blocks is a simple process, and may not warrant any more work.
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:
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:
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 and simple.
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:
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.
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.
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.
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.
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 (
plain_text) in the same place. Read the reference guide for text objects to see an example and full details.
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.
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
block_actions that will be included. Our reference guide contains an outline of this new interaction payload structure.
This payload will also include new
action_id fields, as described below.
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,
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.
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.
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.