Use our app manifest system to create, configure, and copy your Slack apps with ease.
Manifests are YAML or JSON-formatted configurations bundles for Slack apps. With a manifest, you can use a UI or an API to create an app with a pre-defined configuration, or adjust the configuration of existing apps.
You can share and reuse your manifests, giving you a simple way to create development clones of production apps.
Manifests are written in YAML or JSON using a specific structure. Here's a YAML example:
_metadata:
major_version: 1
minor_version: 1
display_information:
name: Zork
long_description: Play the Infocom classic text adventure and find your way to
the end of the maze. ZORK is a game of adventure, danger, and low cunning.
In it you will explore some of the most amazing territory ever seen by
mortals. No workspace should be without one!
description: You are likely to be eaten by a grue.
background_color: "#0000AA"
settings:
socket_mode_enabled: false
interactivity:
is_enabled: true
request_url: https://example.com/slack/message_action
event_subscriptions:
bot_events:
- app_home_opened
features:
app_home:
home_tab_enabled: true
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: zork
slash_commands:
- command: /zork
description: You are standing in an open field west of a white house, with a
boarded front door. There is a small mailbox here.
usage_hint: /zork open mailbox
url: https://example.com/slack/slash/please
oauth_config:
scopes:
bot:
- commands
- chat:write
- chat:write.public
redirect_urls:
- https://example.com/slack/auth
Here's the same example in JSON:
{
"_metadata": {
"major_version": 1,
"minor_version": 1
},
"display_information": {
"name": "Zork",
"long_description": "Play the Infocom classic text adventure and find your way to the end of the maze. ZORK is a game of adventure, danger, and low cunning. In it you will explore some of the most amazing territory ever seen by mortals. No workspace should be without one!",
"description": "You are likely to be eaten by a grue.",
"background_color": "#0000AA"
},
"settings": {
"socket_mode_enabled": false,
"interactivity": {
"is_enabled": true,
"request_url": "https://example.com/slack/message_action"
},
"event_subscriptions": {
"bot_events": [
"app_home_opened"
]
}
},
"features": {
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"bot_user": {
"display_name": "zork"
},
"slash_commands": [
{
"command": "/zork",
"description": "You are standing in an open field west of a white house, with a boarded front door. There is a small mailbox here.",
"usage_hint": "/zork open mailbox",
"url": "https://example.com/slack/slash/please"
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"commands",
"chat:write",
"chat:write.public"
]
},
"redirect_urls": [
"https://example.com/slack/auth"
]
}
}
The following tables describe the settings you can define within an app manifest.
Field | Description | Required |
---|---|---|
_metadata |
A group of settings that describe the manifest | No |
_metadata.major_version |
An integer that specifies the major version of the manifest schema to target. | No |
_metadata.minor_version |
An integer that specifies the minor version of the manifest schema to target. | No |
Field | Description | Required |
---|---|---|
display_information |
A group of settings that describe parts of an app's appearance within Slack. If you're distributing the app via the App Directory, read our listing guidelines to pick the best values for these settings. | Yes |
display_information.name |
A string of the name of the app. Maximum length is 35 characters. | Yes |
display_information.description |
A string with a short description of the app for display to users. Maximum length is 140 characters. | No |
display_information.long_description |
A string with a longer version of the description of the app. Maximum length is 4000 characters. | No |
display_information.background_color |
A string containing a hex color value (including the hex sign) that specifies the background color used on hovercards that display information about your app. Can be 3-digit (#000 ) or 6-digit (#000000 ) hex values. Once an app has set a background color value, it cannot be removed, only updated. |
No |
Field | Description | Required |
---|---|---|
settings |
A group of settings corresponding to the Settings section of the app config pages. | No |
settings.allowed_ip_address_ranges |
An array of strings that contain IP addresses that conform to the Allowed IP Ranges feature | No |
settings.event_subscriptions |
A subgroup of settings that describe Events API configuration for the app. | No |
settings.event_subscriptions.request_url |
A string containing the full https URL that acts as the Events API request URL. If set, you'll need to manually verify the Request URL in the App Manifest section of App Management. |
No |
settings.event_subscriptions.bot_events |
An array of strings matching the event types you want to the app to subscribe to. A maximum of 100 event types can be used. | No |
settings.event_subscriptions.user_events |
An array of strings matching the event types you want to the app to subscribe to on behalf of authorized users. A maximum of 100 event types can be used. | No |
settings.interactivity |
A subgroup of settings that describe interactivity configuration for the app. | No |
settings.interactivity.is_enabled |
A boolean that specifies whether or not interactivity features are enabled. | Yes (if using interactivity settings) |
settings.interactivity.request_url |
A string containing the full https URL that acts as the interactive Request URL. |
No |
settings.interactivity.message_menu_options_url |
A string containing the full https URL that acts as the interactive Options Load URL. |
No |
settings.org_deploy_enabled |
A boolean that specifies whether or not org-wide deploy is enabled. | No |
settings.socket_mode_enabled |
A boolean that specifies whether or not Socket Mode is enabled. | No |
Field | Description | Required |
---|---|---|
features |
A group of settings corresponding to the Features section of the app config pages. | No |
features.app_home |
A subgroup of settings that describe App Home configuration. | No |
features.app_home.home_tab_enabled |
A boolean that specifies whether or not the Home tab is enabled. | No |
features.app_home.messages_tab_enabled |
A boolean that specifies whether or not the Messages tab in your App Home is enabled. | No |
features.app_home.messages_tab_read_only_enabled |
A boolean that specifies whether or not the users can send messages to your app in the Messages tab of your App Home. | No |
features.bot_user |
A subgroup of settings that describe bot user configuration. | No |
features.bot_user.display_name |
A string containing the display name of the bot user. Maximum length is 80 characters. Allowed characters: a-z , 0-9 , - , _ , and . . |
Yes (if bot_user subgroup is included) |
features.bot_user.always_online |
A boolean that specifies whether or not the bot user will always appear to be online. | No |
features.shortcuts |
An array of settings groups that describe shortcuts configuration. A maximum of 5 shortcuts can be included in this array. | No |
features.shortcuts[].name |
A string containing the name of the shortcut. | Yes (for each shortcut included) |
features.shortcuts[].callback_id |
A string containing the callback_id of this shortcut. Maximum length is 255 characters. |
Yes (for each shortcut included) |
features.shortcuts[].description |
A string containing a short description of this shortcut. Maximum length is 150 characters. | Yes (for each shortcut included) |
features.shortcuts[].type |
A string containing one of message or global . This specifies which type of shortcut is being described. |
Yes (for each shortcut included) |
features.slash_commands |
An array of settings groups that describe slash commands configuration. A maximum of 5 slash commands can be included in this array. | No |
features.slash_commands[].command |
A string containing the actual slash command. Maximum length is 32 characters, and should include the leading / character. |
Yes (for each slash command included) |
features.slash_commands[].description |
A string containing a description of the slash command that will be displayed to users. Maximum length is 2000 characters. | Yes (for each slash command included) |
features.slash_commands[].should_escape |
A boolean that specifies whether or not channels, users, and links typed with the slash command should be escaped. | No |
features.slash_commands[].url |
A string containing the full https URL that acts as the slash command's request URL. |
No |
features.slash_commands[].usage_hint |
A string a short usage hint about the slash command for users. Maximum length is 1000 characters. | No |
features.unfurl_domains |
An array of strings containing valid unfurl domains to register. A maximum of 5 unfurl domains can be included in this array. Please consult the unfurl docs for a list of domain requirements. | No |
features.workflow_steps |
An array of settings groups that describe workflow steps configuration. A maximum of 10 workflow steps can be included in this array. | No |
features.workflow_steps[].name |
A string containing the name of the workflow step. Maximum length of 50 characters. | Yes (for each workflow step included) |
features.workflow_steps[].callback_id |
A string containing the callback_id of the workflow step. Maximum length of 50 characters. |
Yes (for each workflow step included) |
Field | Description | Required |
---|---|---|
oauth_config |
A group of settings describing OAuth configuration for the app. | No |
oauth_config.redirect_urls |
An array of strings containing OAuth redirect URLs. A maximum of 1000 redirect URLs can be included in this array. | No |
oauth_config.scopes |
A subgroup of settings that describe permission scopes configuration. | No |
oauth_config.scopes.bot |
An array of strings containing bot scopes to request upon app installation. A maximum of 255 scopes can included in this array. | No |
oauth_config.scopes.user |
An array of strings containing user scopes to request upon app installation. A maximum of 255 scopes can included in this array. | No |
If you receive an invalid_manifest
response when trying to use any App Manifest API, it indicates that the manifest you supplied didn't match the correct schema.
To better locate the problem with your manifest, the invalid_manifest
error should be accompanied by an errors
array:
{
"ok": false,
"error": "invalid_manifest",
"errors": [
{
"message": "Event Subscription requires either Request URL or Socket Mode Enabled",
"pointer": "/settings/event_subscriptions"
},
{
"message": "Interactivity requires a Request URL",
"pointer": "/settings/interactivity"
},
{
"message": "Interactivity requires Socket Mode enabled",
"pointer": "/settings/interactivity"
}
]
}
Each of the items in this array contain a message
which describes the problem, and a pointer
which indicates the problem's location within your supplied manifest. Use these two pieces of info to correct your manifest and try again.
Creating an app from a manifest requires only a few steps:
And that's it — a new app has been created to your manifest specification in less time that it took to read this sentence. If you wish, you can also use App Manifest APIs to create apps programmatically.
App configurations can be modified by editing their manifests using the app config pages. To edit an app's configuration, click on App Manifest in the app config page sidebar. You'll see a manifest editor, which will let you edit your app's configuration in YAML or JSON. Use the same manifest schema as shown above to edit the manifest, and update your app.
Any validation errors will be shown inline, and there are typeahead features to help you update your manifest.
Alternatively, you can use App Manifest APIs to update existing apps programmatically, as explained below.
You can use your manifest YAML or JSON together with a range of APIs that help you to manage your apps:
apps.manifest.create
is used to create apps from JSON manifests.apps.manifest.update
will let you update configurations of your existing apps.apps.manifest.delete
can delete any of your apps.apps.manifest.export
exports the manifest of your existing apps.apps.manifest.validate
will validate any JSON manifest against the correct schema.Each of these API methods should be used with an app configuration access token. Read our guide to learn more about using config tokens.
You can view and export the manifest for any existing app within the app config pages. Simply open your app's config and then browse to the App Manifest section.
From here, you'll be able to directly copy the manifest configuration, or export them to a downloadable file. You can also use the apps.manifest.export
API to export programmatically.
Once exported, you can safely share the manifest with anyone — it doesn't contain any secure information, although you might prefer to keep any request URLs private — or use it yourself to duplicate your app for development purposes.
If you want others to be able to create Slack apps based off of your own app's configuration, you can:
Follow the exporting manifests instructions above to get a file for sharing.
If you want to share your manifest as a link, you can use the following URL pattern:
https://api.slack.com/apps?new_app=1&manifest_yaml=<manifest_here>
Or to share the manifest in JSON format:
https://api.slack.com/apps?new_app=1&manifest_json=<manifest_here>
Ensure you URL encoded the YAML or JSON before sharing the URL.
You can use this URL in any link or button you want — the URL will direct users right into the app creation flow.
Our guided tutorials show you the process of building common app use cases, using Bolt. Every tutorial has its own pre-defined app manifest to allow you to create and configure a new Slack app that's ready to construct.