These are developer-focused instructions that cover posting messages to Slack via APIs. For user instructions on message formatting in your Slack client, refer to this Help Center article.
App surfaces such as messages, modals, or Home tabs can contain all types of textual treasures. The text itself can be formatted and placed inside blocks to create rich message layouts.
The Block Kit elements that form the layouts for these surfaces frequently use text objects to insert all kinds of content. These text objects can be left as unformatted plain_text
or formatted with mrkdwn
to create useful visual highlights or to utilize a certain syntax to trigger special parsing. This reference guide explains all of the mrkdwn
formatting options available to use in text objects.
These instructions are also handy if you are retrieving messages and want to understand how to interpret the formatting syntax.
Let's first look at the various ways to format text.
It's important to know that there are some characters in text strings that must be escaped.
Slack uses &
, <
, and >
as control characters for special parsing in text objects, so they must be converted to HTML entities if they're not going to be used for their parsing purpose. Therefore, if you want to use one of these characters in a text string, you should replace the character with its corresponding HTML entity as shown:
Symbol | HTML entity |
---|---|
& |
& |
< |
< |
> |
> |
You shouldn't HTML entity-encode the entire text, as only the specific characters shown above will be decoded for display in Slack.
mrkdwn
Text objects contain a text
field that can be formatted using a markup language called mrkdwn
.
Use it in most Block Kit text objects by specifying a type
of mrkdwn
. There are, however, a few Block Kit blocks and elements that only allow plain_text
with no formatting — these are called out in the Block Kit reference guides.
mrkdwn
is also the default formatting method for the top-level text
field in a message object when using the Web API to publish a message.
mrkdwn
can be used within secondary message attachments by using the mrkdwn_in
field as shown in the relevant reference guide. This formatting is similar to Markdown markup but with its own syntax, as shown below.
Apply visual styles like so:
_italic_
will produce italicized text*bold*
will produce bold text~strike~
will produce You can use multi-line text in app-generated text. Insert a newline by including the string \n
in your text. For example:
This is a line of text.\nAnd this is another one.
Will produce the following formatting:
This is a line of text.
And this is another one.
You can highlight text as a block quote by using the >
character at the beginning of one or more lines:
This is unquoted text\n>This is quoted text\n>This is still quoted text\nThis is unquoted text again
If you have text that you want to be highlighted like code (like this
), surround it with back-tick (`) characters:
This is a sentence with some `inline *code*` in it.
Text within inline code blocks will not use any other formatting, so it can be useful even if you're not displaying actual code.
You can also highlight larger, multi-line code blocks by placing 3 back-ticks before and after the block:
```This is a code block\nAnd it's multi-line```
There's no specific list syntax in app-published text, but you can mimic list formatting with regular text and line breaks:
- Detective Chimp\n- Bouncing Boy\n- Aqualad
To link to URLs in conversation, include the URL directly in mrkdwn
text and it will be auto-transformed by the server into a link.
URLs with spaces will break, so we recommend that you remove any spaces from your URL links.
This message contains a URL http://example.com/
So does this one: www.example.com
You can also use mrkdwn
to manually add links:
This message contains a URL <http://example.com/>
Adjust the text that appears as the link from the URL to something else:
<http://www.example.com|This message *is* a link>
And create email links:
<mailto:bob@example.com|Email Bob Roberts>
You can also use Block Kit buttons as links by using the url
parameter in button elements.
When you use any of the messaging APIs to retrieve a message, you'll see that auto-transformed URLs are shown in the mrkdwn
format. So this:
This message contains a URL http://example.com/
Will be represented in the API as:
This message contains a URL <http://example.com/>
While this message:
So does this one: www.example.com
Will be retrieved in this form:
So does this one: <http://example.com|www.example.com>
Emoji can be included in their full-color, fully-illustrated form directly in text. Once published, Slack will then convert the emoji into their common 'colon' format. For example, a message published like this:
It's Friday 😄
will be converted into colon format:
It's Friday :smile:
If you're publishing text with emoji, you don't need to worry about converting them, just include them as-is.
If you're retrieving messages, you'll receive the emojis in colon format, so you might want to convert them back to their unicode emoji form. The compatible emoji formats are the Unicode Unified format (used by OSX 10.7+ and iOS 6+), the Softbank format (used by iOS 5) and the Google format (used by some Android devices). These will be converted into their colon-format equivalents.
The list of supported emoji are taken from https://github.com/iamcal/emoji-data.
We told you earlier about the need to escape certain strings in text objects. These strings are used to trigger special parsing of the text, like user mentions or advanced date formatting. Read on to learn more about this advanced formatting.
Text can refer to a Slack channel and transform that reference into a link to the channel itself. This uses a similar mrkdwn
syntax as regular URL links:
Why not join <#C123ABC456>?
#C123ABC456
is the channel's ID. Your app can get this ID from an interaction request payload, from the Event API payload sent when one of the event types occurs, or by looking it up directly with the conversation-related methods of the Web API.
You can also manually retrieve a specific channel's ID from its URL:
https://app.slack.com/client/E123ABC456/C123ABC456
When text containing the channel linking syntax is published in an app surface, the ID will be automatically converted to show the actual name of the conversation.
If any of the channel members do not have access to the linked private channel, they will only see an unclickable private channel
label.
If you're retrieving messages, use the conversations.info
Web API method to look up by channel ID and to find out other relevant information (such as the actual name of the channel).
A mention is a special type of reference that provides a link to the mentioned user's profile in the published text.
If the mention is included in an app-published message, the mentioned user will also be notified about the reference. This Help Center article describes what that notification process looks like.
To mention a user in app-published text, provide their user ID in the following syntax:
Hey <@U012AB3CD>, thanks for submitting your report.
Your app can get this user ID from an interaction request payload, from the Event API payload sent when one of the event types occurs, or by looking them up via the users.list
Web API using another unique piece of information you have about them, such as their email address.
You can also manually retrieve a specific user's ID by clicking the overflow button in their Slack profile, and choosing the Copy member ID
option.
When text containing the user-mention syntax is published by an app, the ID will be automatically converted to show the display name of the user.
If you're retrieving messages, you can use the users.info
Web API method to lookup by user ID and find out other relevant information, such as their display name.
As with users, you can mention user groups, which will link to the group's profile.
If the mention is included in an app-published message, Slack will notify each user in the group about the mention.
To mention a user group in app-published text, to provide the group ID in the following general syntax:
`<!subteam^ID>`
!subteam^
is a literal string that should not change, but ID
should be replaced with the actual user group ID. Here's an example:
Hey <!subteam^SAZ94GDB8>, there's a new task in your queue.
Your app can get this group ID from the Event API payload sent when one of the subteam
event types occurs, or by looking them up via the usergroups.list
Web API. You can also manually retrieve a specific user group's ID from the URL shown when viewing its profile.
When text containing the user group mention syntax is published by an app, the ID will be automatically converted to show the name of the user group.
If you're retrieving messages, you can use the usergroups.list
Web API method to lookup by user group ID and find out other relevant information.
These special groups should be mentioned sparingly, as they tend to notify a large group of users. We don't have any specific guidelines, but use your discretion when mentioning individuals or more specific groups where possible.
There are a few core user groups built into Slack that can be mentioned in app-message text:
@here
notifies only the active members of a channel.@channel
notifies all members of a channel, active or not.@everyone
notifies every person in the #general
channel (i.e. every non-guest member of a workspace).To add these to an app-published message, use the following syntax:
Hey <!here>, there's a new task in your queue.
Text containing a date or time should display that date in the local timezone of the person seeing the text. For app-published text, there is a handy date syntax available to format a Unix timestamp, and Slack will handle the timezone localization for you.
The <!date>
command will format the timestamp using tokens within a string that you set, and it must include some fallback text for older Slack clients. Here's the general syntax to use:
<!date^timestamp^token_string^optional_link|fallback_text>
This can be broken down as follows:
<>
is used as a control character for the whole string, and ^
is used to divide different parts of the string.!date
indicates to use the special date parsing.timestamp
is a number in standard Unix time format, the date and time that you want to include in your text.token_string
should provide a formatting for your timestamp, using plain text along with any of the following tokens:
{date_num}
is displayed as 2014-02-18
. It will include leading zeros before the month and date and is probably best for more technical integrations that require a developer-friendly date format.{date}
is displayed as February 18th, 2014
. The year will be omitted if the date is less than six months in the past or future.{date_short}
is displayed as Feb 18, 2014
. The year will be omitted if the date is less than six months in the past or future.{date_long}
is displayed as Tuesday, February 18th, 2014
. The year will be omitted if the date is less than six months in the past or future.{date_pretty}
displays the same as {date}
but uses "yesterday", "today", or "tomorrow" where appropriate.{date_short_pretty}
displays the same as {date_short}
but uses "yesterday", "today", or "tomorrow" where appropriate.{date_long_pretty}
displays the same as {date_long}
but uses "yesterday", "today", or "tomorrow" where appropriate.{time}
is displayed as 6:39 AM
or 6:39 PM
in 12-hour format. If the client is set to show 24-hour format, it is displayed as 06:39
or 18:39
.{time_secs}
is displayed as 6:39:45 AM
6:39:42 PM
in 12-hour format. In 24-hour format it is displayed as 06:39:45
or 18:39:42
.optional_link
can be provided if your timestamp needs to be linked, specified using a standard, fully qualified URL.fallback_text
should be included just in case the client is unable to process the date. Consider adding timezone information to your fallback text since it will potentially be different from the timezone of the person reading it.Here are some examples of date formatting strings:
<!date^1392734382^Posted {date_num} {time_secs}|Posted 2014-02-18 6:39:42 AM PST>
<!date^1392734382^{date} at {time}|February 18th, 2014 at 6:39 AM PST>
<!date^1392734382^{date_short}^https://example.com/|Feb 18, 2014 PST>
If you're retrieving messages, you will receive the <!date>
string back in its original format, and you can use the information above to parse it if necessary.
Above, we explained how to include various types of special syntax in your app-published text. What we didn't mention is that you can just include the same text as a user would post directly in Slack to achieve some of these things. For example, given the following text:
<http://example.com|example link> http://example.com #general @here 🤩 :smile:
Most of these references can be automatically parsed upon publishing to turn them into links or mentions:
<http://example.com|example link> <http://example.com> <#C0838UC2D|general> <!here> :star-struck: :smile:
You can achieve this in different ways, depending on where the text is being placed:
verbatim
attribute of your text objects to false
. This is actually the default method of processing these text objects.text
field, or text in secondary message attachments, include a link_names
argument with value of 1
when publishing the message — see the reference docs for the relevant publishing method for more information about this.If you want to disable automatic parsing, you have a couple of options depending on the type of text:
verbatim
attribute of your text objects to true
.text
field, or text in secondary message attachments, as long as you exclude the link_names
argument when publishing, this will be disabled by default. Regular URLs will still be converted into clickable links; however, to disable this, you can pass the parse
argument with a value of none
when publishing.Even with this functionality available, we still recommend that you use the manual methods shown above. (This is also why we didn't mention it earlier.)
This is important because the names of conversations or user groups may change at any time. What was previously a functioning reference may no longer work. Meanwhile, an ID will always remain the same. The same holds true for special mentions like @here
.
Another good reason to disable automatic parsing is to be more explicit about where you want to include links and mentions. This could prevent random text from being unintentionally parsed and turned into one. For example, imagine your app passes user input from a third-party service straight into the published text. Using automatic parsing, if this user text contained a string like @everyone
, your app could unintentionally send a notification to the entire workspace.
We've already deprecated this functionality for user mentions, so always parsing manually will keep you prepared in case automatic parsing is deprecated for other entities such as conversations or user groups in the future.
If you want to turn Slack's markdown-like processing off, you have different options depending on where the text is:
type
of your text objects to plain_text
.text
field in messages, include a mrkdwn
attribute set to false
when publishing.mrkdwn_in
attribute.If you're retrieving messages, we've included some extra details in the sections above to help you parse the formatting syntax. This will allow you to properly format it for display on a different service, or to help your app fully understand the intent of a message. Here are the general steps involved in detecting advanced formatting syntax:
<(.*?)>
.#C
as a channel link.@U
or @W
as a user mention.!subteam
as a user group mention.!
according to the rules for special mentions.|
) - if present, use the text following the pipe as the label for the link or mention.We can take message formatting a step further by making rich message layouts with Block Kit, which enables us to structure complex data in a readable and understandable way within messages.
While 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.
You can create messages using blocks and introduce the tools for building a compelling visual experience. Stack individual blocks together into an array that defines the visual layout and style of your app-publishable messages. The Formatting with rich text tutorial illustrates these concepts.
Each block is represented in our APIs as a JSON object. Here's an example of a 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.
Individual blocks can be stacked together to create complex visual layouts.
When you've chosen each of the blocks you want in your layout, 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.
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 sending your message.
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:
chat.postMessage
and chat.postEphemeral
methods in the Web API.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:
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'll 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:
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 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.
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.
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
Congratulations! You've mastered the message composition options available to Slack apps.
✨ To learn about all the blocks and options available, head to the reference guides for layout blocks.
✨ To learn how messages can be used for more than just communicating data and how interactivity can trigger more fine-grained workflows, head to the overview of messaging interactivity.