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

Display

Settings

Features

OAuth

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:

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

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