Create and configure apps with manifests

Use the app manifest system to quickly create, configure, and copy Slack apps.

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. Use this capability to create development clones of production apps.


Creating manifests

Manifests are written in YAML or JSON using a specific structure.

_metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: Zork
  long_description: A very long description.
  description: A shorter description.
  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 see a mailbox in the field.
      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
{
  "_metadata": {
    "major_version": 1,
    "minor_version": 1
  },
  "display_information": {
    "name": "Zork",
    "long_description": "A very long description.",
    "description": "A shorter description.",
    "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 see a mailbox in the field.",
        "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. Maximum 50 items. 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 your app's settings. 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.incoming_webhooks An object with a single boolean property, incoming_webhooks_enabled, that maps to Enabling incoming webhooks via the App config. 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 organization-wide deployment is enabled. No
settings.socket_mode_enabled A boolean that specifies whether or not Socket Mode is enabled. No
settings.token_rotation_enabled A boolean that specifies whether or not token rotation 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 10 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 50 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. Defaults to false. 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 hint about how to use 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

Functions

The function settings should be used when creating custom functions with Bolt, a feature available for net-new apps created through the CLI.

Custom functions for Bolt are in beta and under active development.
Field Description Required
functions.callback_id A unique string identifier representing the function. No other functions in your application may share a callback ID. Changing a function's callback ID is not recommended, as the function will be removed from the app and created under the new callback ID, breaking anything referencing the old function. In the example below, the callback_id is "sample_function". Yes
functions.callback_id.title A string to identify the function. Yes
functions.callback_id.description A succinct summary of what your function does. No
functions.callback_id.input_parameters An object which describes one or more input parameters that will be available to your function. Each top-level property of this object defines the name of one input parameter available to your function. No
functions.callback_id.output_parameters An object which describes one or more output parameters that will be returned by your function. Each top-level property of this object defines the name of one output parameter your function makes available. No

Creating apps using manifests

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

A new app has been created to your manifest specification! 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 page. 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:

Each of these API methods should be used with an app configuration access token.


Managing configuration tokens

Each config token is unique to a user and a workspace, but not an app. This means you can manage the configuration of any of your apps in a single development workspace, with just one config token.

Use the generator below to create and delete your config tokens.

When you create a configuration token, the "Slack Tooling Tokens Vendor" app will be added to the workspace.

Rotating configuration tokens

Each app configuration token will expire 12 hours after it has been generated. In order to continually rotate your config tokens, you are also provided with a refresh token.

It's strongly suggested that you refresh your token before it expires, rather than waiting for it to expire and checking for an error from the Slack API.

In order to refresh config tokens, make a call to tooling.tokens.rotate, using the refresh token in the refresh_token argument. In response you'll receive something like this:

{
	"ok": true,
	"token": "xoxe.xoxp-...",
	"refresh_token": "xoxe-...",
	"team_id": "...",
	"user_id": "...",
	"iat": 1633095660,
	"exp": 1633138860
}

The token field contains your new config access token, which you can then store and use for Manifest API calls. The refresh_token field contains a new refresh token.

The remainder of the response above contains fields which identify the source workspace and user of each token, as well as timestamps which indicate when the token was issued and when it will expire.


Sharing manifests

You can share manifests with others so they can create Slack apps based off of your own app's configurations.

You can view and export the manifest for any existing app within the app config pages. First, 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 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.


Troubleshooting 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.


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 Slack app.


View more tutorials