Designing Slack apps

Slack apps paint with a palette of blocks and conversations. Create a masterpiece by reading our tips for app design and conversational flourish.

---

Designing with intention

Gather feedback and surveys from a diverse range of people within your organization. We don't prescribe what feedback or ideas to seek, but here are some thought experiments to try:

• Are there any regular types of message that are posted manually? Imagine a manager posting in a channel every Friday afternoon asking for status reports. This could be turned into an app that posts reminders on the same schedule. The app could also collect the responses in a better format for the manager to consume later.
• Ask team members to find one or two automated messages that they’ve received in the past week or so that are critical to their job. Often these kinds of automated emails can be turned into messages posted in workspaces by Slack apps.
• Think beyond pure communication and embrace interactivity—an app like the above might just post automated messages. Beyond that, could any other app surfaces be implemented with interactive features to radically deepen the experience.
• Think about the key hurdles that people face when using Slack in your team, and outline them. Can an app solve those problems?
• Do you regularly use an external service while working? If they don't already have their own integration (try the App Directory), and they offer a web-based API, build an app that integrates that service into Slack.

If you need some inspiration, explore the Slack App Directory!

---

Messaging with consideration

Messages that alert users can be incredibly useful. Many Slack apps exist primarily to pipe notifications from external services into relevant channels. Here are some specific considerations that can help ensure the messages your users want don’t turn into noise.

Be upfront about communication

When your app is first installed, allow the installer to easily set preferences that relate to communication. Think about settings like the rate of messages, the channel they should be posted to, and if applicable, the type(s) of notifications your app should send.

Avoid large-group mentions

There are very few cases where your app should send broad mentions like @channel, @here, or @everyone. One exception might be if your app sends a notification for immediate action when a critical system or service goes down. Even then, you should get explicit permission from the installer before your app uses one of these mentions.

Pick the right frequency of notifications

Consider how frequently your messages are generating notifications for a user. When it makes sense, offer the user an option to get a digest of these messages rather than being alerted for individual events. This is especially important when the events are coming from an automatic source like service logs. In extreme cases, sending too many messages can get your token revoked due to rate limits.

When your app generates a lot of notifications, users will notice (and might grow annoyed). This can lead them to remove your app from a channel or even to uninstall the app from the entire workspace. One way to mitigate this is by surfacing messaging preferences often. Make it intuitive for people to use your app how and when they want.

Here's an example of an app that builds a preferences link into the actual messages:

Match message types and channels

You may already be segmenting or categorizing the types of messages that users can receive. If your service already does this, you can make the Slack notification experience even better by giving people the option to pipe different message types into different channels.

For example, an HR tool might want to pipe messages about a candidate’s background check only into #hr-team, but after an offer has been accepted and signed, maybe a #new-hires channel wants to be notified so they can celebrate.

Make messages that notify actionable

Some messages are best being only text that alerts a channel that something happened in a 3rd party system. But what if that user wants to dig into your service after receiving your message? Or what if you send a system status that requires immediate action?

You can save people work by adding action elements directly into your app’s Slack messages. Buttons, select menus, and dialogs let people react in the moment and get work done faster. If your app is considerate with alerts and saves people time, they’ll likely find your app an essential part of their workday.

Learn more about sending messages in our messaging docs.

Sending direct messages to users

First, consider when and whether you should send direct messages (DMs) to specific users. Remember that DMs generate push notifications for mobile users and badges on desktop and mobile. These are useful but also disruptive and can be unexpected, so be cautious with your use of DMs. You should only DM a user when:

• The user sends you a DM first.
• The user is the only one you’re providing a service to, rather than the team.
• Your app is sharing confidential interactions or information.

Users will assume that information shared back and forth with your app in DM is private. Be aware of any sensitive information that’s being shared, and don’t surprise users by announcing results of DM conversations in channel without letting them know first.

By default, apps are set up with a messaging tab that allows the app to broadcast messages only, without needing to anticipate or respond to human interaction.

Need to send a DM? Read our guide to finding conversations via the Web API and then about sending messages.

Responding to users in channel

Whatever you post in channel is going to be long-lived and add to the group conversation that people are reading, both in the moment and later when they may look back at what was shared.

In response to a user action, an app could publish an in-channel message, or an ephemeral message. In-channel response will be visible to all channel members where the user invoked the action. Ephemeral responses will only be visible to the invoking user.

Remember that a chatty app is not necessarily a good thing, so only pick responses that are important to the entire team when posting in-channel.

If the response only needs to be displayed to the user, it’s a better idea to use an ephemeral message than it is to generate a DM.

Read more about ephemeral messages in our Messaging docs.

---

Communicating with clarity

Your app will converse with users frequently, whether via conversational interface or structured interactions. It's vital that the voice and tone of your app's articulation is brief, clear, and human.

Your Slack app is a representation of your brand, and the way your app communicates will become part of your brand voice, especially if you’re building a conversational interface.

No matter how small your team is, even if your team is just you, if you're putting an app into the world (and into Slack), then you have a brand voice. Even if the only place it’s used right now is in this one app.

This presents a great opportunity: you can thoughtfully define what your brand voice is. The best thing to do is think of this voice as an extension of your own voice.

How much personality is too much?

Always remember that your app’s primary purpose is to help users accomplish a task - even if that task is inherently entertaining, like finding just the right cat GIF. It's great if your app sounds clever and entertaining - just please ensure that these traits don't obstruct the user's ability to complete the work your app is assisting them with.

Foreground the information necessary to the task at hand, then add voice and tone elements like you would add seasoning to your favorite dish. They should enhance what’s already there, not overpower or overwhelm the reader’s senses.

You want your voice to differentiate yourself from the crowd. Using contractions and conversational cadence is a good way to lightly infuse your app with human personality - “You’ll be able to” rather than “You will” and that sort of thing.

A little goes a long way. We cannot say this enough.

Be brief

Nearly every word your app says should facilitate an interaction (courteous parts of speech, such as greetings, are also useful).

Don’t add a joke or aside just to be glib. If you have to add sentence upon sentence in order to make a joke, it's probably not worth it.

Like this

Not like this

The first example still has plenty of distinctive personality, but gets straight to the point, and doesn’t risk users choosing not to wade through unimportant content.

Be clear

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

• Don’t use jargon and slang in the important parts of message text
• Avoid culturally specific references, like jokes from movies
• Stick to common, understandable words
• Buttons labels should be clear and specific
• Make buttons active-voice and reflect the user’s outcome (Save, Book Flight, Place Order)
• Avoid vague, non-actionable text like Click here or Settings
• Don’t replace words with emoji

If you choose to include puns or wordplay, make sure they focus a user's attention, rather than creating a distraction.

Like this

Not like this

The second example is confusing in two ways: it includes a reference to an obscure film, and the emojis it uses may stall some users as they try to decipher their meanings (“Fire... meat? Firemeat?”).

The message button copy is also unclear and confusing, potentially preventing users from selecting any response at all. We recommend using standard combinations on buttons (Attend/Decline, Confirm/Cancel) to help your users have a smooth experience with your app.

Read over your copy and ask yourself, “Is there anywhere a user may pause in confusion?” If so, rewrite.

Be empathetic

All kinds of people use Slack, and we previously described how important it is to understand that variation in terms of their ability to use your app properly. But that diversity is also important when thinking about the tone you use to communicate with them.

Ensure that your voice and tone express empathy toward every single person who uses your app. Some basic steps to take include:

• Use gender-neutral pronouns.
• Use a variety of emoji skin tones.
• Don’t use sexist, racist, or ableist language.
• Make an effort to trial your voice and tone with people from a diversity of backgrounds, in different settings (on mobile, with flaky wifi, etc.).
• Don’t assume any level of technical fluency from your users - keep instructions clear.
• Writing for a broad audience takes a bit of practice if you’re new to it, and it is usually easier if you have a diverse team of people working on your app from the start.
• If you decide to give gender to your app (and it’s very easy not to), then be appropriate with the kind of things it says - make sure it doesn't use any stereotypes or generalizations.

A final note: informality is good, but getting too friendly is often seen as grating or culturally insensitive (particularly in a workplace).

Spend time rewriting

We spend a good amount of time at Slack writing, rewriting, agonizing over, and then rewriting just once more to get every sentence as good as we can make it. If you’ve worked with a professional writer before, you know that no one gets it right the first time.

Here are some techniques we find helpful in revising:

• Read your work out loud to yourself. Ah, you found a typo, didn’t you?
• Find someone to read your script out loud with, to prototype the two-part interaction.
• Rewrite as though you’re writing to a friend. Does that sound more natural or human?.
• Record yourself verbally explaining the concepts you’re trying to convey. This may help you find a more casual way of expressing your app’s message.

After a few rounds of revision, your app should be ready to help your users accomplish tasks in Slack, while avoiding confusion, frustration, and consternation. Congratulations!

---

Onboarding users to your app

Your app only has one chance to make a first impression with users, so it's worth the time to make your onboarding experience a great one. Your app should provide a great experience for everybody in a potentially diverse audience.

When people first interact with your app inside of Slack, they may have varying context about your app and what it does:

• They may have used it before
• They may be familiar with your app on another platform, but using it in Slack for the first time
• They may have seen others on their team using the app, but have not used it themselves
• They may know nothing about your app at all

Your onboarding should equip people to get something done as quickly as possible, no matter what context they have. Determine the key tasks you need a user to accomplish in the first 30 seconds of interacting with your app, and design your onboarding to help them get it done.

When to start onboarding

Since we don't recommend DMing users out of the blue, your app will need to cue off events to begin onboarding. One such nifty notification is the app_home_opened event. It lets you know that a user has clicked on a DM with your app, entering the App Home space. It's the perfect time to begin on an onboarding flow.

Many events can trigger onboarding, though, so it's important to make sure that you're looking out for more than just app_home_opened.

For example, if a user invokes one of your app's slash commands, their onboarding should start then, rather than waiting for the app_home_opened event. Relatedly, this user's onboarding would take a slightly different form, because using a slash command indicates a different level of expertise than clicking on your app to interact with it.

Say hello 👋

It's a good idea to have an app announce its presence and teach people how to interact with it. There is, however, a fine line between being informative and being spammy. Here's how to do it right:

Have an informative, concise welcome message When someone installs your app, it's a good idea to DM that person with a welcome message. A welcome message should be concise, and clearly state what your app does, while including instructions on how to use it.

🧠 Thought Starter: What is the call to action for the user installing your app? Should they add your app to a specific channel? Should they (or their admin) link a 3rd party account?

Make the call to action clear and actionable from your welcome message. Without a clear call to action, it's likely that the installing user won't configure your app properly and won't get the full value from it.

Introducing yourself to the team Do not DM the entire team, as unexpected messages from an app can prompt uninstallation. Only the installing user should receive a direct message from your app.

If your app has a bot user, it should say hello when it's added to a new channel. In addition to explaining the app's purpose, the bot user should give a quick explanation of how to use your app and what configurations have been set (if any). For example, if your app is going to post a daily update at 10am, that's helpful to know.

💡 Design Tip: If your app has help documentation hosted on your website or if people can DM your app for help, now's a great time to let them know.

Make deeper dives opt-in Your welcome message should contain enough information to help someone complete a task for the first time. That said, you may want to help people use your app beyond the first quick-win scenario. Let people choose to have an extended walkthrough for more complex tasks, especially if your app allows users to do more than one thing.

🧠 Thought Starter: Any non-essential onboarding past an app's welcome message should be skippable. Some users who appear new may have used your app before on other Slack teams. Others will find your app intuitive enough that they'd prefer not to be helped. Design with user optionality in mind --- in other words, let users choose when to skip non-essential onboarding.

Offer help

Onboarding is really about proactively helping people use your app. That said, even after a well-designed onboarding experience, users may still have questions about your app or may come back later and forget the onboarding you led them through.

Provide a help action When slash commands are a central part of your app's experience, it's common practice to provide a help action, e.g. /myapp help, that will offer the user assistance. Perhaps provide more information about your app and listing your app's commands.

If your app is more conversational, then reply in your app's DM when a user asks for help or your app doesn't understand something a user says to you.

💡 Design Tip: If you're designing an app with more than one workflow, it can be helpful to offer a select menu in your help message that gives users the option to kick off any of your app's workflows to see what they are and how they work.

Respond when your app is @mentioned When your app is @mentioned, a user probably wants to use your app or doesn't know how to use your app but wants to learn. This is another good moment to surface help to the user and allow them to start using your app as quickly as possible.

⚙️ Development Tip: Listening to app_mention event in the Events API will send you a payload every time someone directly @mentions your bot user.

Help and feedback sometimes look alike People don't just want to reach you when they're critically stuck. Sometimes, they'll want to give feedback on things like the ease of going through a particular workflow, or whether a bot successfully understood their intent. If you have a place to route feedback requests, provide a way for people to get there inside Slack. Only offer a feedback channel if you plan to collect and review feedback.

Make your app visible

There are a few things you can do before your app is event installed to help potential users discover and install your app.

App suggestions If a user posts a link from your website into channel, there's a good chance they might want to install your app. As part of the app directory, your app can suggest users install your Slack app when links associated with your domain are posted in a channel. This helps users less familiar with the App Directory (or with Slack apps in general) find your app in the first place.

You can find HTML code to embed on your website on your app management page. Learn more about app suggestions in our App Directory guide.

Install directly from the App Directory Direct install creates less friction for people thinking about installing your app. Instead of redirecting them from the App Directory to your site to install the app, you can provide a Direct Install URL, which redirects the current user to Slack's OAuth authorize step directly.

Learn more about Direct Install in our App Directory guide.