Thoughtful app onboarding

Clear and timely communication of your Slack app’s value using the app_home_opened event

So you’ve made an awesome app! Now it’s time to educate your users about it.

Tip: If you’re not familiar with Slack’s Events API, I highly recommend reading this documentation.

Knowing the exact moment to send a message

Recently released, app_home_opened is an event that Slack app developers can subscribe to and triggers every time a user opens a DM with your app.

The initial seconds of interaction with your app determine whether people view it as useful, or not. By subscribing to this new event, you now have more control over timely communication and that crucial first impression.

This can be applied in many ways. To name a few:

• 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 few times they open the DM. We recommend every five times, but it’s totally up to you! (Make sure your app remains helpful, and not overly “talkative” or spammy.)
• Welcome back: If a user hasn’t interacted with your app in a while, 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.

How to get started

1. Find your App Settings: Go to https://api.slack.com and then click on Your Apps and select your app.
2. Click on Event Subscriptions
3. Click Add Workspace Event
4. Select app_home_opened and you’re good to go!

Tip: You will need to resubmit your app if it’s listed on the Slack App Directory. That usually doesn’t take too long.

How to code

If you’re using node, there’s a really in depth article on it here. Here’s a modified code snippet from the article that shows how to subscribe to the event and what the payload would look like:

// Rough Adaptation from the link above
const { createEventAdapter } = require('@slack/events-api');
const slackSigningSecret = process.env.SLACK_SIGNING_SECRET;
const port = process.env.PORT || 3000;

// Initialize the adapter to trigger listeners with the full body
const slackEvents = createEventAdapter(slackSigningSecret, {
 includeBody: true,
});


slackEvents.on('app_home_opened', (event, body) => {
  console.log(event);
})

(async () => {
  const server = await slackEvents.start(port);
  console.log(`Listening for events on ${server.address().port}`);
})();
// Alternatively, if you're using express you might do this:
app.post("/slack/events", slackEvents.expressMiddleware());

And the event payload looks (roughly) like this:

{ channel: "C1234", user: "U1234", type: "app_home_opened" }

The body object has more useful metadata:

{
  api_app_id: "A123",
  authed_users: ["U123", "U124"],
  event: { 
    channel: "C1234", 
    user: "U1234", 
    type: "app_home_opened"
  },
  event_id: "123";
  event_time: 1313.13;
  team_id: "T1234";
  token: "token";
  type: "app_home_opened";
}

Gotchas

Remember, this event fires every time someone opens your app’s DM. If you want a user to receive the message one time only, your app is responsible for keeping track of that state.

Also, existing users may already work extensively with your app. However, if they haven’t opened a DM lately, once you enable app_home_opened, they’ll receive an onboarding message, which might cause some confusion or irritation. At Halp, we check if a user is associated with a ticket to determine their eligibility for an onboarding message.

Another thing to think about — if you post a message, should it be ephemeral or regular? We opted for a regular message, since it’s preserved in chat history. This way, the user can refer back or pin the message for easy finding.

See it in action

We used the app_home_opened event to improve our app’s onboarding experience. Halp is a Slack-first IT ticketing system that has a unique set of onboarding challenges: There are three different types of users that need to be onboarded at varying stages of the workflow, fulfilling distinct objectives.

1. Admins are onboarded when the they first install the app and must configure it for their workspace.
2. Once setup is complete, agents learn to create and manage tickets.
3. When the IT team is ready for company-wide rollout, end users are taught to report issues through the app.

A sample message from the perspective of an agent who just clicked into the app DM for the first time.

For end users, we explain that our app helps them streamline internal requests. We also tell them how to create a ticket — including a message button for clear and actionable next steps.

A sample message from the perspective of an end user who just clicked into the app DM for the first time.

Continuously improving user experience

App onboarding is never straightforward. You should invest a lot of time and thought into it. Luckily, Slack has given us yet another tool to help delight our users.

We’d love to hear how you’re using the app_home_opend event (or other features) to create great Slack experiences.

Check out Halp’s freshly updated onboarding flow. Get started by visiting their listing in the Slack App Directory.