Welcome users to your App Home using events

The rundown
Read next:An overview of modals

An App Home is a private, one-to-one space in Slack shared by a user and an app. Each App Home contains a number of tabbed surfaces, including a Messages tab for app-user conversation, and a Home tab that can be fully customized by the app.

To learn more about how you can use your app's Home tab to create a multitude of app experiences, start reading our guide to the Home tab.

The Events API provides a subscription type, app_home_opened, that is particularly useful to apps that want to unlock the full potential of the App Home.

Read on to see more about using the Events API with your App Home. Learn how your app can know when users have opened the App Home, and what you can do in response.

New App Home

BETA
Block kit in app home tab

Build a surface for your app with Block Kit to display info, ways to use your app, and more in a dedicated UI just for your app.

The message tab becomes optional

Skip unnecessary conversation and use Block Kit in the home tab exclusively. If you’d rather not converse with users, disable the direct messaging tab for your app.

An illustration of an app's home

Detecting visitors to your App Home

The app_home_opened event is well-named — it tells your app when the App Home has been opened. A payload will be delivered to your app via the Events API, containing actionable and contextual information about the event.

This information will include the user that opened the App Home, the workspace that the event happened in, and more. Here's a basic example:

{
    "type": "app_home_opened",
    "user": "U061F7AUR",
    "channel": "D0LAN2Q65",
    "event_ts": "1515449522000016",
    "tab": "home",
    "view": {
        ...
    }
}

This context will help your app decide how to respond.

For example, the event_ts field is a timestamp dated that identifies within a few seconds when the user opened the window. Your app might store this, along with the user and channel IDs, so you can keep track of when, if ever, your app last interacted with a user in your App Home.

Read the app_home_opened reference guide for more details on some of these fields.

If you need more information about the user and have the appropriate scopes, use users.info in the Web API. Want to know more about the conversation that forms the App Home Messages tab? Use conversations.info.


Welcoming users into your Home

A user opening your App Home represents clear intent or interest in your app, an invitation to converse or serve.

There are many options for responding to such an event, following are a few short examples from many.

Onboarding new users

First impressions are important. The first time a user opens an App Home, you should send them a greeting and guide them through the features of your app.

Use the event to trigger a helpful and informative onboarding flow.

This is especially important if they are the installer of the app, where they may need to configure options for the entire workspace.

Read our guide to onboarding users for more tips on how to approach this.

Boost user familiarity with regular tips

Randomize a set of tips for power usage of your app, and display them to a user at varying cadences when they open the App Home.

Make sure to go the extra mile and give users control of how often these reminders come.

Re-engage frequent visitors

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.

Provide updates on your app

Keep your users informed of the latest app improvements, new functionality or features released. But don't just market to them.

Prompt for configuration

Messages and Home tabs are buses for all kinds of interactivity — help users configure your app in a safe place, away from public channels and potentially embarrassing moments of performance art.


Using the Messages tab

The Messages tab in an App Home provides a space for the app and user to converse.

Before your app can see App Home messages sent by the user, the app must subscribe to the message.im event.

You'll then receive an Events API notification for every message sent to your app via the Messages tab. The im:history scope is required for this event type.

Your app can then choose to respond to those messages in whatever way you see fit.

Read our guides to messaging for Slack apps for more details on how to enrich your app's messages with rich layouts and interactivity.


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.