Go to Slack

Creating rich message layouts

Structure complex data in an easily readable and understandable way within messages.

We've already introduced you to the range of message text formatting options that can improve information density and visual hierarchy at a basic level.

Now it's time to take this further by using 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

Blocks fit neatly into the basic message structure. As shown in our reference guide to message payloads, a blocks field should be provided.

That blocks field is an array of different Block Kit components that form the layout of the message. Before proceeding, finish our guide to building blocks to understand how to stack different components together to create that blocks array.

This blocks field is then included within the message payload at the top level, like this:

{
  "channel": "C1H9RESGL",
  "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://google.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"
        }
      ]
    }
  ]
}

When you're using blocks in your message payload, the text field becomes a fallback message displayed in notifications. Blocks should otherwise define the entire desired visible message, so include everything within that blocks array.

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:

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:

Message with blocks showing a review of a hotel with 1 stars given

View this example


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:

Message with blocks showing a review of a hotel with 1 stars given, and secondary content showing alternative hotel options

Building attachments

Secondary content can be attached by using a top-level attachments array within your message JSON payload. Within that array, you can include an object containing a second-level blocks array, constructed in the same way as within the top-level. Here's the JSON payload from the example above:

{
  "channel": "CBR2V3XEX",
  "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.