Creating rich message layouts
Structure complex data in an easily readable and understandable way within messages.
Message text formatting can improve information density and visual hierarchy at a basic level.
You can combine that with Block Kit layout blocks and block elements to vastly expand the possibilities for visual organization.
This guide will show you how to create messages using blocks and introduce the tools for building a compelling visual experience.
Adding blocks to messages
You can stack individual blocks together into an array that defines the visual layout and style of your app-publishable messages.
First, let's look at the structure of individual blocks.
Define a single block
Each block is represented in our APIs as a JSON object. Here's an example of a simple section block:
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "New Paid Time Off request from <example.com|Fred Enriquez>\n\n<https://example.com|View request>"
}
}
Every block contains a type field — specifying which of the available blocks to use — along with other fields that describe the content of the block.
Block Kit Builder is a visual prototyping sandbox that will let you choose from, configure, and preview all the available blocks.
If you want to skip the builder, the block reference guide contains the specifications of every block, and the JSON fields required for each of them.
Stacking multiple blocks
Individual blocks can be stacked together to create complex visual layouts.
When you've chosen each of the blocks you want in your layout, simply place each of them in an array, in visual order, like this:
[
{
"type": "header",
"text": {
"type": "plain_text",
"text": "New request"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Type:*\nPaid Time Off"
},
{
"type": "mrkdwn",
"text": "*Created by:*\n<example.com|Fred Enriquez>"
}
]
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*When:*\nAug 10 - Aug 13"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|View request>"
}
}
]
Block Kit Builder will allow you to drag, drop, and rearrange blocks to design and preview Block Kit layouts.
Alternatively you can use the block reference guide to manually generate a complete blocks array, like the one shown above.
Adding your blocks array
Blocks are added to messages by adding a blocks array to the message payload, like this:
{
"channel": "C123ABC456",
"text": "New Paid Time Off request from Fred Enriquez",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "New request"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Type:*\nPaid Time Off"
},
{
"type": "mrkdwn",
"text": "*Created by:*\n<example.com|Fred Enriquez>"
}
]
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*When:*\nAug 10 - Aug 13"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|View request>"
}
}
]
}
When you're using blocks in your message payload, the top-level text field becomes a fallback message displayed in notifications. Blocks should define everything else about the desired visible message.
Now it's time to show off your creation by publishing your message.
Sending messages with blocks
There are multiple ways for apps to send messages, and you can use Block Kit with most of them. Here's a list of the methods you can use to publish messages with blocks:
- Incoming webhooks.
chat.postMessageandchat.postEphemeralmethods in the Web API.- In response to slash commands.
- In response to message actions.
- You can also use blocks when creating Slack app based URL unfurls.
There are no special OAuth scopes needed to publish blocks, beyond those already specified within the methods above.
Read our guide to sending messages to get started with that process for your app. Once you've decided which sending method to use, consult that method's reference guide to find out where to include your JSON payload.
When you call your selected method, your stack of blocks will transform into a beautiful new message, like this:
Adding secondary attachments
This feature is a legacy part of messaging functionality for Slack apps. We recommend you stick with Block Kit as above, but if you still want to use attachments, read our caveats below.
When you use blocks as we described above, they will appear in the top-level of your message. This is the best location for primary content, the data and information that is unmissable and important.
However, you can attach things to a secondary part of the message, content that adds further context or additional information but isn't vital.
The screenshot below shows the previous example, but with some secondary content added:
Building attachments
Secondary content can be attached by using a top-level attachments array within your message JSON payload:
{
"channel": "C123ABC456",
"attachments": [
{
"fallback": "Plain-text summary of the attachment.",
"color": "#2eb886",
"pretext": "Optional text that appears above the attachment block",
"author_name": "Bobby Tables",
"author_link": "http://flickr.com/bobby/",
"author_icon": "http://flickr.com/icons/bobby.jpg",
"title": "Slack API Documentation",
"title_link": "https://api.slack.com/",
"text": "Optional text that appears within the attachment",
"fields": [
{
"title": "Priority",
"value": "High",
"short": false
}
],
"image_url": "http://my-website.com/path/to/image.jpg",
"thumb_url": "http://example.com/path/to/thumb.png",
"footer": "Slack API",
"footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png",
"ts": 123456789
}
]
}
Within the attachments array, you can also include a second-level blocks array, constructed using Block Kit blocks and elements. Here's the JSON payload from the Block Kit example we created before, this time inside of an attachment:
{
"channel": "C123ABC456",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "Danny Torrence left the following review for your property:"
}
},
{
"type": "section",
"block_id": "section567",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|Overlook Hotel> \n :star: \n Doors had too many axe holes, guest in room 237 was far too rowdy, whole place felt stuck in the 1920s."
},
"accessory": {
"type": "image",
"image_url": "https://is5-ssl.mzstatic.com/image/thumb/Purple3/v4/d3/72/5c/d3725c8f-c642-5d69-1904-aa36e4297885/source/256x256bb.jpg",
"alt_text": "Haunted hotel image"
}
},
{
"type": "section",
"block_id": "section789",
"fields": [
{
"type": "mrkdwn",
"text": "*Average Rating*\n1.0"
}
]
}
],
"attachments": [
{
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Alternative hotel options*"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|Bates Motel> :star::star:"
},
"accessory": {
"type": "button",
"text": {
"type": "plain_text",
"text": "View",
"emoji": true
},
"value": "view_alternate_1"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|The Great Northern Hotel> :star::star::star::star:"
},
"accessory": {
"type": "button",
"text": {
"type": "plain_text",
"text": "View",
"emoji": true
},
"value": "view_alternate_2"
}
}
]
}
]
}
Secondary attachments have a few additional parameters that can be included within each object in the attachments array. Take a look at our reference guide for secondary attachments to see the full list.
When should I use secondary attachments?
Secondary attachments are a legacy part of the messaging functionality. While we aren't deprecating them, you should understand that they might change in the future, in ways that reduce their visibility or utility.
We've already mentioned that we recommend the attachments array only contain secondary content that is less important to the intent of the published message.
Any content displayed within attachments may be wrapped, truncated, or hidden behind a "show more" style option by Slack clients. This isn't the case with the top-level blocks field.
In short, we recommend you use Block Kit for as much of your message composition as you can, and avoid using attachments if possible. Blocks have many more visual and interactive capabilities available.
Current limitations
At launch, messages built with blocks will not be supported in “All unreads”, “Threads”, “Pinned”, “Starred”, and “Shared Messages” views in Slack. Instead, users will see:
This message can't be shown in full here. View message
We’re working actively to support these views as soon as possible.
Making things interactive
Congratulations! You've hopefully mastered the message composition options available to Slack apps. From here, you can go on to read the reference guides for layout blocks if you want to learn more about all the blocks and options available.
You can also take your generic, colorful, interlocking plastic brick structure (😉) to the next level and learn how to introduce interactivity to your messages. These docs will show you how messages can be used for more than just communicating data: how interactivity can trigger more fine-grained, useful workflows. Start with our overview of messaging interactivity.