Go to Slack

Your App Home

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read first:Enabling interactions with botsMessaging for Slack apps
Read next:Creating an onboarding experienceAn overview of interactivity

Your Slack app lives in a virtual place called an App Home. Users find it by locating or adding your app in their channel sidebar, under the Apps heading.

Your App Home is essentially a private, 1:1 conversation between a person and your bot user. It works just like a direct message between two users, using the same events and Web API methods.

Greet users with interactive, educational experiences and unlock the full potential of your App Home using the app_home_opened event.

Welcoming users

To interact with people who open your Slack app, you'll need to:

Let's learn who the user is and where to direct follow up communications. A user opening an App Home represents clear intent or interest in your app, an invitation to converse or serve.

Detecting when an App Home is opened

A bot user is required to treat a direct message conversation like an App Home and receive a app_home_opened event.

By subscribing to the app_home_opened, delivered via the Events API, your app will receive actionable information about the user and workspace.

The event contains four top-level fields:

{
    "type": "app_home_opened",
    "user": "U061F7AUR",
    "channel": "D0LAN2Q65",
    "event_ts": "1515449522000016"
}

You'll find the event_ts to be within a few seconds (hopefully sooner!) of when the user opened the window. You might want to store this along with the user and channel ID so you can keep track of when, if ever, you last interacted with a user in an App Home.

If you need more information about the user and have the appropriate scopes, use users.info. Want to know more about the App Home direct message channel? Use conversations.info.

Posting a message to the App Home

First impressions are important. The first time a user opens an App Home, especially if they are the installer of the app, you should send them a greeting and guide them through what your bot user can do.

We recommend posting colorful, easy to parse messages with clear interactive actions when onboarding users.

Typically, you'll post messages in one of three ways to an App Home:

Both the user and channel IDs found in the app_home_opened event can be used as the channel parameter in chat.postMessage. If you're using an incoming webhook or response_url, we recommend sticking with the explicitly ID'd channel.

Using Block Kit and interactive features like buttons and dialogs in tandem with your messages can take your App Home beyond simple chat.

Optional: Subscribing to App Home messages

For many apps, the two approaches above are all that's needed to provide an engaging App Home experience.

You probably want to subscribe to the message.im event, which will also require im:history scope. Otherwise, any messages lovingly typed by hand will be never be seen or responded to.

You'll then receive every message sent to your app via direct message and can choose to respond to those messages in whatever way you see fit.

Other ways to use but not abuse your App Home

Welcoming users who show up to your App Home's doorstep is just the beginning. Liven up the place with these tips while respecting people's time and attention:

  • Onboarding: Send a friendly welcome message that clearly articulates your app's value, primary ways to use it, and actionable next steps.
  • Tips: You can randomize a set of tips, and send them to a user every month or so when they open the App Home. Go the extra mile and give users control of how often — if at all — these reminders come.
  • Welcome back: If a user hasn't interacted with your app in a while, and you receive a app_home_opened event, send them a message that welcomes them back and reinforces your app's value, primary ways to use it, and actionable next steps.
  • Product updates: Keep your users informed of the latest app improvements, new functionality or features released. But don't just market to them.
  • Configuration: The message is a bus for all kinds of interactivity — help users configure your app or bot in a safe place, away from public channels and potentially embarrassing moments of performance art.

Tools, samples, and inspiration

Here are some resources if you're looking for where to go next.

  • Dig in to this example Node.js app written to handle the app_home_opened event and more on Glitch. It uses our Bolt framework.
  • Browse onboarding templates in Block Kit Builder, our message prototyping tool.
  • Read Rolling out the Red Carpet and learn about building great onboarding experiences on Slack.

Make your App Home where your app's heart is.