Guidelines for building messages

These docs describe an outmoded approach to composing messages and interactive experiences. Learn how to more effectively communicate and help folks get work done by our new documentation and transitioning to "blocks".
The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read first:Block Kit
Read next:Messaging for Slack apps

Making your messages interactive allows you to provide more value to your users. It enables them to complete tasks quickly in the context of their conversation and workflow without having to navigate elsewhere.

A gorgeous message

Like guidelines? We have even more in our UI best practices guide.

Stay in the Flow

Interactions should focus on what members are trying to do right then and there. Instead of offering many options, focus on the simple, common tasks that make sense to complete inside of Slack conversations.


Good: Limited button selections


Bad: Too many button selections

Keep Formatting Simple

Attachments allow you to add richer formatting to messages as well as buttons. Use the least amount of formatting needed.

Basic message attachments

How message formatting appears

Message with thumbnail attachment

Message with thumbnail

Message with image attachment

Message with image

Mobile message attachments

On iOS and Android, our message attachments render something like:

Basic mobile message attachments

Message formatting on mobile

Mobile message with thumbnail attachment

Message formatting with thumbnail on mobile

Mobile message with image attachment

Message formatting with image on mobile

Don't get too attached

Don't use an attachment when regular message text will suffice, and don't send multiple attachments when a single attachment will do.

And never ever (ever!) send more than 20 attachments.

Like this

Good: Keep it simple

Not like that

Bad: Uh-oh, this is unnecessary

Great: This is one attachment

Good: Limited button selections

Uh-oh: This is three

Bad: Uh-oh too many pieces of flair

The difference is small, yes, but Slack prefers consolidated messages.

Each attachment should represent an object so if there's a title for it, it should be inside the attachment.

Good idea

Good: Title in attachment

Bad idea

Bad: Unattached title

Making messages colorful

Colorful bars guarding the edge of messages and their components definitely make them more distinctive.

Use color bars a few ways: Utilize your brand color to complement your app's avatar to more clearly brand your messages. Your service may already associate specific colors with workflow transition types and objects — use the colors that will most clearly resonate with our common users.

When you're not harmonizing with your brand, we suggest using the default light gray. If you're looking for just a little more distinction, consider using optional color values good, warning, or danger.

Use simple buttons

Keep Buttons Simple Too

Choose between three button styles: Default (default), Primary (primary), and Destructive (danger).

Primary buttons

Use Primary buttons when there's a single primary action you want to highlight next to other default buttons. Put the primary button before the default buttons.

Destructive buttons

Use a destructive button when there's a single primary action you want to highlight that is a destructive action. Also put the destructive button before the default buttons.

If the destructive action is potentially catastrophic or may inspire a deep sense of regret, offer a clear confirmation step before proceeding.

Use non-default buttons sparingly. There should only be one non-default button per attachment to help users quickly identify what their options are.

Please don't use emoji in your buttons. Decorate your messages with their mirthful magic instead.

The life of an action

After a user takes an action, try to update the message to reflect the current state. This may mean replacing the buttons with a confirmation of what they've selected. You can do this by either updating the first message or removing it and sending a new one. Try to keep elements in place so users can quickly see what has changed. Also check that someone who is seeing this message later can understand what has happened.

First interaction with message buttons

If there are multiple steps in an interaction, consider replacing the parts of the message and buttons along the way instead of just adding messages, and cleaning up the entire interaction at the end to summarize the entire interaction.

First interaction with message buttons

Make a choice.

The choice is made.

Showing a large number of items.

Please don't display a long list of items.

Try to show the most likely options first and, if you must, use buttons to paginate items. Try to replace the list instead of adding new messages.

Avoid cluttering up the conversation for everyone by using ephemeral messages in conversations when displaying items as an intermediary step of an action.

Sending the right type of message to the right place.

You have a few options on the type of message to send:

When it's useful for everyone in the channel to see the actions or that an action has been taken, just send a regular message to that channel.

Everyone should see this.

If a user has initiated an action that has multiple steps, those steps should be shown as ephemeral messages visible only to that user until the entire action is complete to avoid cluttering the channel for everyone.

Only the interacting user should see this.

If you want to show actions or messages only to certain people, then you can send them a DM instead.

Everyone should see this.

If actions expire, update the message when that has occurred with information on how to start it again.

Building a successful app

Create a storyboard of your app's interactions before you start implementing it. It's a great way to remain user-centric and provide the most valuable and pleasant experience possible.

Writing for Global Audiences

Words and copy used in your interactions should be easily understood even by someone who doesn't speak the same language fluently.

  • Avoid jargon and slang.
  • For basic actions, stick to common, simple words.
    • Yes or No is better than Affirmative or Get me out of here!
  • Be concise; carefully consider using more than a couple of words on a button
  • Buttons labels should be clear and specific.
    • Avoid vague, non-actionable text like Click here or Settings
    • Make buttons active-voice and reflect the user's outcome (Save, Book Flight, Place Order)
  • Use title case.