Reference: blocks

Actions block

Holds multiple interactive elements.

Fields

Examples

An actions block with a select menu and a button:

View this block in Block Kit Builder

{
  "type": "actions",
  "block_id": "actions1",
  "elements": [
    {
      "type": "static_select",
      "placeholder":{
          "type": "plain_text",
          "text": "Which witch is the witchiest witch?"
      },
      "action_id": "select_2",
      "options": [
        {
          "text": {
              "type": "plain_text",
              "text": "Matilda"
          },
          "value": "matilda"
        },
        {
          "text": {
              "type": "plain_text",
              "text": "Glinda"
          },
          "value": "glinda"
        },
        {
          "text": {
              "type": "plain_text",
              "text": "Granny Weatherwax"
          },
          "value": "grannyWeatherwax"
        },
        {
          "text": {
              "type": "plain_text",
              "text": "Hermione"
          },
          "value": "hermione"
        }
      ]
    },
    {
      "type": "button",
      "text": {
          "type": "plain_text",
          "text": "Cancel"
      },
      "value": "cancel",
      "action_id": "button_1"
    }
  ]
}

An actions block with a datepicker, an overflow, and a button:

View this block in Block Kit Builder

{
  "type": "actions",
  "block_id": "actionblock789",
  "elements": [
    {
      "type": "datepicker",
      "action_id": "datepicker123",
      "initial_date": "1990-04-28",
      "placeholder": {
        "type": "plain_text",
        "text": "Select a date"
      }
    },
    {
      "type": "overflow",
      "options": [
        {
          "text": {
            "type": "plain_text",
            "text": "*this is plain_text text*"
          },
          "value": "value-0"
        },
        {
          "text": {
            "type": "plain_text",
            "text": "*this is plain_text text*"
          },
          "value": "value-1"
        },
        {
          "text": {
            "type": "plain_text",
            "text": "*this is plain_text text*"
          },
          "value": "value-2"
        },
        {
          "text": {
            "type": "plain_text",
            "text": "*this is plain_text text*"
          },
          "value": "value-3"
        },
        {
          "text": {
            "type": "plain_text",
            "text": "*this is plain_text text*"
          },
          "value": "value-4"
        }
      ],
      "action_id": "overflow"
    },
    {
      "type": "button",
      "text": {
        "type": "plain_text",
        "text": "Click Me"
      },
      "value": "click_me_123",
      "action_id": "button"
    }
  ]
}

Context block

Displays contextual info, which can include both images and text.

Fields

Example

View this block in Block Kit Builder

{
  "type": "context",
  "elements": [
    {
      "type": "image",
      "image_url": "https://image.freepik.com/free-photo/red-drawing-pin_1156-445.jpg",
      "alt_text": "images"
    },
    {
      "type": "mrkdwn",
      "text": "Location: **Dogpatch**"
    }
  ]
}

Divider block

Visually separates pieces of info inside of a message.

A content divider, like an <hr>, to split up different blocks inside of a message. The divider block is nice and neat, requiring only a type.

Fields

Example

View this block in Block Kit Builder

{
  "type": "divider"
}

File block

Displays a remote file.

You can't add this block to app surfaces directly, but it will show up when retrieving messages that contain remote files.

If you want to add remote files to messages, follow our guide.

Fields

Example

{
  "type": "file",
  "external_id": "ABCD1",
  "source": "remote",
}

Header block

Displays a larger-sized text block.

A header is a plain-text block that displays in a larger, bold font. Use it to delineate between different groups of content in your app's surfaces.

Fields

Example

View this block in Block Kit Builder

{
  "type": "header",
  "text": {
    "type": "plain_text",
    "text": "A Heartfelt Header"
  }
}

Image block

Displays an image.

An image block, designed to make those cat photos really pop. Supported file types include png, jpg, jpeg, and gif.

Fields

Examples

The following three examples show different ways to get the following result:

An image block using image_url:

View this block in Block Kit Builder

{
  "type": "image",
  "title": {
    "type": "plain_text",
    "text": "Please enjoy this photo of a kitten"
  },
  "block_id": "image4",
  "image_url": "http://placekitten.com/500/500",
  "alt_text": "An incredibly cute kitten."
}

An image block using slack_file with a url:

View this block in Block Kit Builder

{
  "type": "image",
  "title": {
    "type": "plain_text",
    "text": "Please enjoy this photo of a kitten"
  },
  "block_id": "image4",
  "slack_file": {
    "url": "https://files.slack.com/files-pri/T0123456-F0123456/xyz.png"
  },
  "alt_text": "An incredibly cute kitten."
}

An image block using slack_file with a id:

View this block in Block Kit Builder

{
  "type": "image",
  "title": {
    "type": "plain_text",
    "text": "Please enjoy this photo of a kitten"
  },
  "block_id": "image4",
  "slack_file": {
    "id": "F0123456",
  },
  "alt_text": "An incredibly cute kitten."
}

Input block

Collects information from users via block elements.

Read our guides to collecting input in modals or in Home tabs to learn how input blocks pass information to your app.

Fields

Example

An input block containing a plain-text input element:

View this block in Block Kit Builder

{
  "type": "input",
  "element": {
    "type": "plain_text_input"
  },
  "label": {
    "type": "plain_text",
    "text": "Label",
    "emoji": true
  }
}

Rich text block

Displays formatted, structured representation of text.

It is also the output of the Slack client's WYSIWYG message composer, so all messages sent by end-users will have this format. Use this block to include user-defined formatted text in your Block Kit payload. While it is possible to format text with mrkdwn, rich_text is strongly preferred and allows greater flexibility.

You might encounter a rich_text block in a message payload, as a built-in type in workflow apps, or as output of the rich_text_input block element.

Fields

Rich text blocks can be deeply nested. For instance: a rich_text_list can contain a rich_text_section which can contain bold style text. More details on how that works is shown in the examples.

Sub-elements are what comprise the elements array in a rich text block. There are four available rich text object sub-elements.: rich_text_section, rich_text_list, rich_text_preformatted, and rich_text_quote. Because many of the elements include a section block, the details of that element are listed first, followed by the others.

Section element: rich_text_section

{
"type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Hello there, I am a basic rich text block!"
        }
      ]
    }
  ]
},
{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Hello there, "
        },
        {
          "type": "text",
          "text": "I am a bold rich text block!",
          "style": {
            "bold": true
          }
        }
      ]
    }
  ]
},
{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Hello there, "
        },
        {
          "type": "text",
          "text": "I am an italic rich text block!",
          "style": {
            "italic": true
          }
        }
      ]
    }
  ]
},
{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Hello there, "
        },
        {
          "type": "text",
          "text": "I am a strikethrough rich text block!",
          "style": {
            "strike": true
          }
        }
      ]
    }
  ]
}

List element: rich_text_list

{
  "type": "rich_text",
  "block_id": "block1",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "My favorite Slack features (in no particular order):"
        }
      ]
    },
    {
      "type": "rich_text_list",
      "elements": [
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Huddles"
            }
          ]
        },
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Canvas"
            }
          ]
        },
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Developing with Block Kit"
            }
          ]
        }
      ],
      "style": "bullet",
      "indent": 0,
      "border": 1
    },
  ],
}

{
  "type": "rich_text",
  "block_id": "block1",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Breakfast foods I enjoy:"
        }
      ]
    },
    {
      "type": "rich_text_list",
      "style": "bullet",
      "elements": [
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Hashbrowns"
            }
          ]
        },
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Eggs"
            }
          ]
        }
      ]
    },
    {
      "type": "rich_text_list",
      "style": "bullet",
      "indent": 1,
      "elements": [
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Scrambled"
            }
          ]
        },
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Over easy"
            }
          ]
        }
      ]
    },
    {
      "type": "rich_text_list",
      "style": "bullet",
      "elements": [
        {
          "type": "rich_text_section",
          "elements": [
            {
              "type": "text",
              "text": "Pancakes, extra syrup"
            }
          ]
        }
      ]
    }
  ]
}

Preformatted code block element: rich_text_preformatted

The following are the properties of the link object option in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_preformatted",
      "elements": [
        {
          "type": "text",
          "text": "{\n  \"object\": {\n    \"description\": \"this is an example of a json object\"\n  }\n}"
        },
      ],
      "border": 0
    }
  ]
}

Quote element: rich_text_quote

{
  "type": "rich_text",
  "block_id": "Vrzsu",
  "elements": [
    {
      "type": "rich_text_quote",
      "elements": [
        {
          "type": "text",
          "text": "What we need is good examples in our documentation."
        }
      ]
    },
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Yes - I completely agree, Luke!"
        }
      ]
    }
  ]
}

Rich text element types

For the rich text elements that have a field of elements, the following types are possible.

broadcast

The following are the properties of the broadcast object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "broadcast",
          "range": "everyone"
        }
      ]
    }
  ]
}

color

The following are the properties of the color object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "color",
          "value": "#F405B3"
        }
      ]
    }
  ]
}

channel

The following are the properties of the channel object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "channel",
          "channel_id": "C123ABC456"
        }
      ]
    }
  ]
}

date

The following are the properties of the date object type in the elements array.

Date format strings

The following are the template strings allowed by the format property of the date element type.

• {day_divider_pretty}: Shows today, yesterday or tomorrow if applicable. Otherwise, if the date is in current year, uses the {date_long} format without the year. Otherwise, falls back to using the {date_long} format.
• {date_num}: Shows date as YYYY-MM-DD.
• {date_slash}: Shows date as DD/MM/YYYY (subject to locale preferences).
• {date_long}: Shows date as a long-form sentence including day-of-week, e.g. Monday, December 23rd, 2013.
• {date_long_full}: Shows date as a long-form sentence without day-of-week, e.g. August 9, 2020.
• {date_long_pretty}: Shows yesterday, today or tomorrow, otherwise uses the {date_long} format.
• {date}: Same as {date_long_full} but without the year.
• {date_pretty}: Shows today, yesterday or tomorrow if applicable, otherwise uses the {date} format.
• {date_short}: Shows date using short month names without day-of-week, e.g. Aug 9, 2020.
• {date_short_pretty}: Shows today, yesterday or tomorrow if applicable, otherwise uses the {date_short} format.
• {time}: Depending on user preferences, shows just the time-of-day portion of the timestamp using either 12 or 24 hour clock formats, e.g. 2:34 PM or 14:34.
• {time_secs}: Depending on user preferences, shows just the time-of-day portion of the timestamp using either 12 or 24 hour clock formats, including seconds, e.g. 2:34:56 PM or 14:34:56.
• {ago}: A human-readable period of time, e.g. 3 minutes ago, 4 hours ago, 2 days ago.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "date",
          "timestamp": 1720710212,
          "format": "{date_num} at {time}",
          "fallback": "timey"
        }
      ]
    }
  ]
}

emoji

The following are the properties of the emoji object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "emoji",
          "name": "basketball"
        },
        {
          "type": "text",
          "text": " "
        },
        {
          "type": "emoji",
          "name": "snowboarder"
        },
        {
          "type": "text",
          "text": " "
        },
        {
          "type": "emoji",
          "name": "checkered_flag"
        }
      ]
    }
  ]
}

link

The following are the properties of the link object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "link",
          "url": "https://api.slack.com"
        }
      ]
    }
  ]
}

text

The following are the properties of the text object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "text",
          "text": "Hello there, "
        },
        {
          "type": "text",
          "text": "I am a bold rich text block!",
          "style": {
            "bold": true
          }
        }
      ]
    }
  ]
}

user

The following are the properties of the user object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "user",
          "user_id": "U123ABC456"
        }
      ]
    }
  ]
}

usergroup

The following ar the properties of the usergroup object type in the elements array.

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        {
          "type": "usergroup",
          "usergroup_id": "G123ABC456"
        }
      ]
    }
  ]
}

Section block

Displays text, possibly alongside block elements.

A section can be used as a text block, in combination with text fields, or side-by-side with certain block elements.

Fields

Examples

A text section block:

View this block in Block Kit Builder

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

A section block containing text fields:

View this block in Block Kit Builder

{
  "type": "section",
  "text": {
    "text": "A message *with some bold text* and _some italicized text_.",
    "type": "mrkdwn"
  },
  "fields": [
    {
      "type": "mrkdwn",
      "text": "High"
    },
    {
      "type": "plain_text",
      "emoji": true,
      "text": "Silly"
    }
  ]
}

A section block containing a datepicker element:

View this block in Block Kit Builder

{
  "type": "section",
  "text": {
		"text": "*Haley* has requested you set a deadline for finding a house",
    "type": "mrkdwn"
  },
  "accessory": {
    "type": "datepicker",
    "action_id": "datepicker123",
    "initial_date": "1990-04-28",
    "placeholder": {
      "type": "plain_text",
      "text": "Select a date"
    }
  }
}

Video block

Displays an embedded video player.

A video block is designed to embed videos in all app surfaces (e.g. link unfurls, messages, modals, App Home) — anywhere you can put blocks! To use the video block within your app, you must have the links.embed:write scope.

The metadata received in the block payload will be used to construct the description, provider, and title of the video in all clients. Developers have the flexibility to leave non-mandatory fields null and use other blocks to format this content.

Requirements

• Video blocks can only be posted by apps; users are not allowed to post embedded videos directly from Block Kit Builder.
• Your app must have the the links.embed:write scope for both user and bot tokens.
• video_url has to be included in the unfurl domains specified in your app.
• video_url should be publicly accessible, unless the app relies on information received from the Events API payloads to make a decision on whether the viewer(s) of the content should have access. If so, the service could create a unique URL accessible only via Slack.
• video_url must be compatible with an embeddable iFrame.
• video_url must return a 2xx code OR 3xx with less than 5 redirects and an eventual 2xx.
• video_url must not point to any Slack-related domain.

Constraints

• Embeddable video players only (audio-only permitted)
• Navigation, scrolling and overlays are not allowed within the iFrame.
• Interactivity (e.g. likes, comments, and reactions) are allowed within your player but shouldn't completely overlay or navigate away from the content being embedded. These interactions will be anonymous since no user data is transferred to the embedded view.

Fields

Example

View this block in Block Kit Builder

{
  "type": "video",
  "title": {
    "type": "plain_text",
    "text": "Use the Events API to create a dynamic App Home",
    "emoji": true
  },
  "title_url": "https://www.youtube.com/watch?v=8876OZV_Yy0",
  "description": {
    "type": "plain_text",
    "text": "Slack sure is nifty!",
    "emoji": true
  },
  "video_url": "https://www.youtube.com/embed/8876OZV_Yy0?feature=oembed&autoplay=1",
  "alt_text": "Use the Events API to create a dynamic App Home",
  "thumbnail_url": "https://i.ytimg.com/vi/8876OZV_Yy0/hqdefault.jpg",
}