Rich text block

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

Fields

Field	Type	Description	Required?
`type`	String	The type of block. For a rich text block, `type` is always `rich_text`.	Required
`elements`	Object[]	An array of rich text objects - `rich_text_section`, `rich_text_list`, `rich_text_preformatted`, and `rich_text_quote`. See your specific desired element below for more details.	Required
`block_id`	String	A unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. `block_id` should be unique for each message or view and each iteration of a message or view. If a message or view is updated, use a new `block_id`.	Optional

Usage info

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.

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`

Field	Type	Description	Required?
`type`	String	The type of sub-element; in this case, `rich_text_section`.	Required
`elements`	Object []	An array of rich text elements.	Required

rich_text_section example

An example of a rich_text_section block

{
"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`

Field	Type	Description	Required?
`type`	String	The type of sub-element; in this case, `rich_text_list`.	Required
`style`	String	Either `bullet` or `ordered`, the latter meaning a numbered list.	Required
`elements`	Object []	An array of `rich_text_section` objects containing two properties: `type`, which is "rich_text_section", and `elements`, which is an array of rich text element objects.	Required
`indent`	Number	Number of pixels to indent the list.	Optional
`offset`	Number	Number of pixels to offset the list.	Optional
`border`	Number	Number of pixels of border thickness.	Optional

rich_text_list example

An example of a rich_text_list block

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

Let's say we want to create a nested list, for example something that looks like this:

Breakfast foods I enjoy:

Hashbrowns
Eggs
- Scrambled
- Over easy
Pancakes, extra syrup

To create that in rich text, create three instances of rich_text_list, the middle one using the indent property to indent the types of eggs into that sub-list.

{
  "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`

Field	Type	Description	Required?
`type`	String	The type of the sub-element; in this case, `rich_text_preformatted`.	Required
`elements`	Object []	An array of rich text elements.	Required
`border`	Number	Number of pixels of border thickness.	Optional

rich_text_preformatted example

An example of a rich_text_preformatted block

{
  "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`

Field	Type	Description	Required?
`type`	String	The type of the sub-element; in this case, `rich_text_quote`.	Required
`elements`	Object []	An array of rich text elements.	Required
`border`	Number	Number of pixels of border thickness.	Optional

rich_text_quote example

An example of a rich_text_quote block

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "broadcast".	Required
`range`	String	The range of the broadcast; value can be `here`, `channel`, or `everyone`. Using `here` notifies only the active members of a channel; `channel` notifies all members of a channel; `everyone` notifies every person in the #general channel.	Required

broadcast example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "color".	Required
`value`	String	The hex value for the color.	Required

color example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "channel".	Required
`channel_id`	String	The ID of the channel to be mentioned.	Required
`style`	Object	An object of six optional boolean properties that dictate style: `bold`, `italic`, `strike`, `highlight`, `client_highlight`, and `unlink`.	Optional

channel example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case "date".	Required
`timestamp`	Number	A Unix timestamp for the date to be displayed in seconds.	Required
`format`	String	A template string containing curly-brace-enclosed tokens to substitute your provided `timestamp`. See details below.	Required
`url`	String	URL to link the entire `format` string to.	Optional
`fallback`	String	Text to display in place of the date should parsing, formatting or displaying fail.	Optional

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.

date example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "emoji".	Required
`name`	String	The name of the emoji; i.e. "wave" or "wave::skin-tone-2".	Required
`unicode`	String	Represents the unicode code point of the emoji, where applicable.	Optional

emoji example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case "link".	Required
`url`	String	The link's url.	Required
`text`	String	The text shown to the user (instead of the url). If no text is provided, the url is used.	Optional
`unsafe`	Boolean	Indicates whether the link is safe.	Optional
`style`	Object	An object containing four boolean properties: `bold`, `italic`, `strike`, and `code`.	Optional

link example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "text".	Required
`text`	String	The text shown to the user.	Required
`style`	Object	An object containing four boolean fields, none of which are required: `bold`, `italic`, `strike`, and `code`.	Optional

text example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case, "user".	Required
`user_id`	String	The ID of the user to be mentioned.	Required
`style`	Object	An object of six optional boolean properties that dictate style: `bold`, `italic`, `strike`, `highlight`, `client_highlight`, and `unlink`.	Optional

user example

{
  "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.

Field	Type	Description	Required?
`type`	String	The type of object; in this case "usergroup".	Required
`usergroup_id`	String	The ID of the user group to be mentioned.	Required
`style`	Object	An object of six optional boolean properties that dictate style: `bold`, `italic`, `strike`, `highlight`, `client_highlight`, and `unlink`.	Optional

usergroup example

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

Fields​

Usage info​

Section element: rich_text_section​

List element: rich_text_list​

Preformatted code block element: rich_text_preformatted​

Quote element: rich_text_quote​

Rich text element types​

broadcast​

color​

channel​

date​

Date format strings​

emoji​

link​

text​

user​

usergroup​