Go to Slack

Publishing and updating your app's Home tab

The rundown
Read next:An overview of modals

The Home tab is currently in open beta.
During this beta, features documented below are subject to more swift change than might otherwise be expected from Slack app features. Subscribe to our changelog to be informed as soon as the beta ends.

An app's Home tab can be published and updated at the app's whim.

Publish a single tab design to all your users on a regular schedule. Alternatively, publish a personalized, dynamic tab for each user that updates upon interaction.

This guide will take you through the steps necessary to publish and update an app's Home tab for a user at any time.


Getting started with your app's Home tab

Before we begin, if you don't already have a Slack App, click the following button to create one:

Create your Slack app


1. Preparing your app to use Home tab features

To start using your app's Home tab, you'll need to opt-in to the App Home beta.

Enable Home tab

  • Open your app's management dashboard
  • Click on App Home in the sidebar
  • Click Join beta, then read and accept the terms to continue
  • Enable the Home tab toggle if it's not already enabled

You can also now disable the Messages tab of your App Home, if you wish.

The Home tab is now enabled, but there's a couple more things to configure.

Enable Interactive Components

To use Block Kit's interactive components within your Home tab, you'll need to enable Interactive Components in your app's management dashboard.

We explain what these settings do, what request URLs and interaction payloads are, and how to enable interactivity in our guide to handling user interaction.

Request necessary permissions

Your app will need permission to update the Home tab for users. The best way to do this is by requesting a bot scope during installation and authorization.

Luckily, when you joined the App Home beta earlier, the bot scope was automatically added to your app's default scopes list. This is the list of scopes requested when the app is first installed.

Now you'll need to install your app. For single workspace apps this is simple:

If your app was previously installed, and didn't request the bot scope, you'll need to reinstall it to authorize this new scope. Just click the Reinstall App button that appears in OAuth & Permissions in your app's management dashboard.

Once installed, make note of the Bot User OAuth Access Token that appears on the OAuth & Permissions page, you'll need to use it later.

Things are a bit different for apps that are distributed to multiple workspaces. In that case, apps have to be re-authorized for each workspace by an admin after the bot scope is added. You can read about this in our authorization guide.

Your app's Home tab will now appear within your App Home, but it will be empty. Keep reading to implement a simple example.


2. Composing a view

The Home tab is composed of a single view that can contain up to 100 layout blocks. The view payload is created by an app, then sent via HTTP POST request to the views.publish Web API method.

That view payload is a JSON object that contains a blocks array that defines the layout composition, alongside other fields explained in our reference guide.

Our guide to building with Block Kit explains how you can make even more complex blocks arrays to use within this view payload.

For the purposes of this example we'll stick to a very simple payload and layout:

{ 
   "type":"home",
   "blocks":[ 
      { 
         "type":"section",
         "text":{ 
            "type":"mrkdwn",
            "text":"A simple stack of blocks for the simple sample Block Kit Home tab."
         }
      },
      { 
         "type":"actions",
         "elements":[ 
            { 
               "type":"button",
               "text":{ 
                  "type":"plain_text",
                  "text":"Action A",
                  "emoji":true
               }
            },
            { 
               "type":"button",
               "text":{ 
                  "type":"plain_text",
                  "text":"Action B",
                  "emoji":true
               }
            }
         ]
      }
   ]
}

You can view this simple example within our Block Kit Builder tool to understand how it will appear when published.

Your view payload is ready, so let's see how to use it with views.publish to create a Home tab.


3. Publishing a view to your Home tab

As mentioned, views.publish is one of our Web API methods. If you need an introduction to the Web API, read our guide to the basics, but you'll be able to complete this example even without that knowledge.

The views.publish reference guide explains the other arguments that are required to use the API. Here's how to use them for our example:

  • token - This is the bot token we asked you to make note of earlier in this guide.
  • user_id - For this example, this is your user ID. You can find this within Slack by opening your profile, clicking on the button and choosing Copy member ID.

Beyond this example, apps can get a user's ID programmatically by subscribing to the app_home_opened event, from interaction payloads, or from the many other places you can encounter a user_id.

Now let's make the call to views.publish with the above values in mind:

POST https://slack.com/api/views.publish
Content-type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
{
  "user_id": "YOUR_USER_ID",
  "view": { 
       "type":"home",
       "blocks":[ 
          { 
             "type":"section",
             "text":{ 
                "type":"mrkdwn",
                "text":"A simple stack of blocks for the simple sample Block Kit Home tab."
             }
          },
          { 
             "type":"actions",
             "elements":[ 
                { 
                   "type":"button",
                   "text":{ 
                      "type":"plain_text",
                      "text":"Action A",
                      "emoji":true
                   }
                },
                { 
                   "type":"button",
                   "text":{ 
                      "type":"plain_text",
                      "text":"Action B",
                      "emoji":true
                   }
                }
             ]
          }
       ]
    }
}

If your API call was a success, you'll get a success response containing ok: true.

Navigate to your App Home, click on the Home tab, and you'll see your newly created layout:

Sample Block Kit layout in app's Home tab showing text and a couple of interactive buttons


4. Updating your Home tab

Updating a Home tab uses the exact same process as above, we just need a slightly different blocks array:

POST https://slack.com/api/views.publish
Content-type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
{
  "user_id": "YOUR_USER_ID",
  "view": { 
       "type":"home",
       "blocks":[ 
          { 
             "type":"section",
             "text":{ 
                "type":"mrkdwn",
                "text":"A simple stack of blocks for the simple sample Block Kit Home tab."
             }
          },
          { 
             "type":"actions",
             "elements":[ 
                { 
                   "type":"button",
                   "text":{ 
                      "type":"plain_text",
                      "text":"Action A",
                      "emoji":true
                   }
                },
                { 
                   "type":"button",
                   "text":{ 
                      "type":"plain_text",
                      "text":"Action B",
                      "emoji":true
                   }
                }
             ]
          },
          { 
             "type":"section",
             "text":{ 
                "type":"mrkdwn",
                "text":"And now it's slightly more complex."
             }
          }
       ]
    }
}

Make this API call, and your Home tab will update automatically to reflect the new content:

Updated sample Block Kit layout in app's Home tab showing text and a couple of interactive buttons

Your app can change as much (or as little) of the existing layout as it wants during an update.

In a real world context, apps will need to store user_ids of Home tab users, along with any relevant customizations for individual users. This is because Home tab updates can happen when a user isn't interacting with Slack or the app — for example if a Home tab update was triggered by an external service.


Next steps

🎉 Congratulations — time to arrange the house-warming party! If you've reached this point, you've learned everything that's necessary to publish and update Home tabs.

But there's much more to learn about within the space that the Home tab provides.

Interactivity in Home tabs

Earlier in this guide we mentioned enabling interactive components. This feature allows interactivity within a Home tab, furnished by Block Kit components.

If you try clicking on the buttons in the example Home tab we just created, you'll see that they don't do anything other than display an error icon. That's because even though you can publish interactive components without setting things up, users won't be able to use them until you do.

To learn more about interactivity in Slack apps — including guidance about why and when to update Home tabs — start with our overview of the interactive flow. Read more about enabling interactive components specifically in our guide to handling user interactivity.

Block Kit layouts

Take a deeper dive into Block Kit and find out about the full range of layout blocks and elements available to use in Home tabs.

Pair with modals

Modals are a type of app surface ideal for requesting and collecting data from users. Interactive components within Home tabs can trigger modals, allowing apps to take input and respond accordingly.

Home tabs and modals are powerful features separately — combining them allows your app to scale even greater heights. Read our guide to using modals to learn more.