HomeSurfacesHome tabs

Welcome users to your App Home using events

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.

Upgrade to App Home

Block Kit in the Home tab

Build a persistent, dynamic space for your app using Block Kit. The Home tab provides a dedicated space for your app to connect with users.

The Messages tab becomes optional

Apps can focus on the Home tab exclusively. If you’d rather your app not converse with users, you can disable the Messaging tab entirely.

Try it out by creating an app
Get started

An illustration of an app's homeLearn moreTry Home tab apps
Google Calendar

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, ensure the Messages tab is enabled in the app's configuration in Features > App Home > Show Tabs > Messages Tab.

Additionally, 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.
Next steps

Was this page helpful?