Create and configure apps with manifests

Use our app manifest system to create, configure, and copy your Slack apps with ease.

What are manifests?

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.

Creating manifests

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"
    ]
  }
}

Manifest schema

The following tables describe the settings you can define within an app manifest.

Metadata

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

Display

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

Settings

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

Features

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)

OAuth

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

Correcting schema errors

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 apps using manifests

Creating an app from a manifest requires only a few steps:

Click here.
Choose to create an app from an app manifest.
Pick a development workspace and click Next.
Paste your manifest configuration in the input field provided and click Next.
Review and verify that the configuration you entered matches the summary and click Create.

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.

Updating configurations via manifests

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.

Using the App Manifest APIs

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.

Exporting manifests

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.

Sharing manifests

If you want others to be able to create Slack apps based off of your own app's configuration, you can:

Share the manifest file with them directly, or
Encode your manifest in a shareable link or button.

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.

Try pre-defined manifests

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.

Post messages on a schedule

Responding to app mentions

Hello World Slack app using Bolt

How to quickly get and use a Slack API token

Posting messages using curl

Hello World

View more tutorials

Was this page helpful?