Publishing and updating your app's Home tab
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:
1. Preparing your app to use Home tab features
To start using your app's Home tab, you'll need to enable the Home tab.
Request necessary permissions
Your app will need at least one permission to enable the Home tab. While it doesn't matter which scope(s) your app adds, it must have at least one scope during the installation and authorization process.
Now you'll need to install your app. For single workspace apps this is simple:
- Open your app's management dashboard
- Click on OAuth & Permissions in the sidebar
- If your app doesn't already have a scope, select a scope under Bot token scopes
If you want your app to use the Messages tab in the App Home, you may want to add the chat:write scope here.
Enable Home tab
- Open your app's management dashboard
- Click on App Home in the sidebar
- Under Show Tab, 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 now you'll need to install your app.
- Click on Install App in the sidebar
- Click Allow to install the app to your workspace
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.
Your app's Home tab will now appear within your App Home, but it will be empty. Keep reading to implement a simple example.
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.
2. Composing a view
The Home tab is composed of a single view that can contain up to 100 layout blocks. The view object is created by an app, then sent via HTTP POST request to the views.publish Web API method.
That view object 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 object.
For the purposes of this example we'll stick to a very simple object 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 object 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.
views- This is our view object JSON object created above.
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:
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:
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.
Deep linking into Home tabs
You can use a special deep-linking syntax to directly navigate users to different parts of Slack. This syntax can create links to open conversations, share files, and it can even link a user right into your App Home:
slack://app?team={WORKSPACE_ID}&id={APP_ID}
This syntax can also be modified to link directly to a specific tab within an App Home:
slack://app?team={WORKSPACE_ID}&id={APP_ID}&tab=home
Read our deep-linking reference guide for the specifics.
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.
Gathering input in Home tabs
In order to capture user input, a special type of Block Kit component called an input block is available.
An input block can hold a plain-text input (single or multi-line), checkboxes, radio buttons, a select menu, or a multi-select menu.
The values of any input blocks in a Home tab will be returned in the state field in block_actions payloads when the interactive element in the block is used.
If you've already prepared your app for interactions as above, you are ready to receive these payloads. If not, you'll need to setup your app to handle user interactions.
Each input block will only return a block_actions payload when the dispatch_action flag is set to true on that block. Consult the input block reference for details on that flag and other fields.
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 in a more focused space 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.