Go to Slack

Creating rich message layouts

Add rich layouts to your messages to structure complex data in an easily readable and understandable way.

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

Now it's time to take this further by using layout blocks and block elements to vastly expand the possibilities for visual organization.

This guide will show you how to compose a message using blocks and introduce the tools for building a compelling visual experience.


Getting started with layout blocks

We tricked you with this section header! There's no special setup needed to start using blocks. But just like when you open a new pack of generic, colorful, interlocking plastic bricks (😉), you might want to follow the instructions first.

Building blocks

While those other interlocking bricks are made of plastic, message blocks are composed of JSON data, like this:

{
  "type": "section",
  "text": {
    "type": "mrkdwn",
    "text": "A message *with some bold text* and _some italicized text_."
  }
}

View this example

The JSON here describes a simple text section block, and highlights the general structure of blocks - each contains a type to choose which of the different blocks to use, and then a series of fields that describe what is included in the block.

You can also see how the mrkdwn formatting that we've covered before can be included inside of the text objects in a block.

A stack of blocks

Blocks are stacked together within a JSON array in visual order, like this:

[
    {
        "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"
            }
        ]
    }
]

View this example

You'll use the array of blocks later on in this guide. First let's see how to pick out the blocks you want to add to the stack.

Choosing blocks

Slack provides a long list of blocks to choose from: some contain static content, some provide interactive components, and all can be stacked together to create the Empire State Building of messages.

After emptying that metaphorical box of blocks onto the floor, you could go ahead and start putting them together by editing the raw JSON. However, we have something to help you plan out the message masterpiece you want.

The builder tool is a visual prototyping sandbox that will let you pick and choose and from all available blocks, and stack them together in the way you want.

If you want to skip the builder, the layout blocks reference guide contains the specifications of every block, and the JSON fields required for each of them.

Sending your message

There are multiple ways for apps to send messages, and you can use blocks 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.

Putting blocks in messages

Once you've chosen your message-sending-method, and have prepared your array of blocks, you just need to add that array to your message's JSON payload. The array of blocks is assigned to an easy-to-remember field called blocks. This blocks field is included within the 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. Each of the publishing methods shown above have docs that explain how to use that method, and where to include your JSON payload. When you call your chosen 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 layout blocks 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 layout blocks 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.