App manifests

App manifests are YAML or JSON files that contain the configuration for Slack apps and workflow automations.

➡️ For non-workflow apps, the app manifest can help you quickly create, configure, and copy Slack apps. You can share and reuse these manifests. Use this capability to create development clones of production apps.

➡️ For workflow automation apps, the manifest holds the details of your app’s configuration, declaring the custom types, steps, workflows, and more that the automation contains.

Manifest concepts

All apps have a manifest. Manifests are reusable configurations; they are designed to make an app's configuration "portable". You can store a manifest in version control such as GitHub where collaborators can easily grasp the setup of your app. Manifests can also make testing easier for apps that have the same setup.

Manifests are expressed in JSON or YAML and can be authored in your app's configuration page. The Deno SDK provides additional tooling for authoring manifests in the language of the framework.

➡️ If you are developing with the Deno SDK, use the required reference fields on the workflow apps manifest page for your source of truth.

Currently, there are two versions of app manifests. Workflow automations exclusively use version 2, while Slack apps may use either version. If the version _metadata property is not specified, Slack will treat your manifest configuration as v1. The properties outlined below indicate which manifest version they are included in.

Manifests for non-workflow apps

App manifests be created and managed by visiting Your Apps, selecting the app, then navigating to Features > App Manifest or directly by using the App Manifest API.

When you create an app through Your Apps using the Create New App button, you have an option to create from scratch or from an existing app manifest. This is how you could replicate a manifest from another app, pasting the recycled manifest there.

✨ Read more on the Create and configure apps with manifests page for Slack apps page.

Manifests and the Deno SDK

For workflow automation apps created with the Deno SDK, keep your local manifest.ts or manifest.js file up-to-date with any custom types, steps, datastores, and workflows required for your app.

✨ Read more on the App manifest page for workflow apps page.

Manifest schema

Manifests are written in YAML or JSON using a specific structure. Deno Slack SDK enables writing manifests in TypeScript. Here is an example of what one might look like in each language.

_metadata:
  major_version: 2
  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": 2,
    "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"
    ]
  }
}
import { Manifest } from "deno-slack-sdk/mod.ts";
import SampleWorkflow from "./workflows/sample_workflow.ts";
import SampleObjectDatastore from "./datastores/sample_datastore.ts";

/**
 * The app manifest contains the app's configuration. This
 * file defines attributes like app name and description.
 * https://api.slack.com/future/manifest
 */
export default Manifest({
  name: "welcomebot",
  description: "Quick and easy way to setup automated welcome messages for channels in your workspace.",
  icon: "assets/icon.png",
  workflows: [SampleWorkflow],
  outgoingDomains: [],
  datastores: [SampleObjectDatastore],
  botScopes: [
    "commands",
    "chat:write",
    "chat:write.public",
    "datastore:read",
    "datastore:write",
  ],
});

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

Metadata

Field Description Required v1 v2
_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

Slack Marketplace

The fields in this section are only relevant for apps that intend to be distributed via the Slack Marketplace.

Field Description Required v1 v2
app_directory An object containing information to be listed in the Slack Marketplace. No
app_directory.app_directory_categories An array of strings. No
app_directory.use_direct_install Boolean value if the app should use direct install. No
app_directory.direct_install_url A string URL of the install page, following the pattern ^https?:\/\/. No
app_directory.installation_landing_page A string URL of the installation landing page, following the pattern ^https?:\/\/. Yes (if app_directory subgroup is included)
app_directory.privacy_policy_url A link to your app's privacy policy. Yes (if app_directory subgroup is included)
app_directory.support_url A link to your app's support URL. Yes (if app_directory subgroup is included)
app_directory.support_email An email address to contact your app's support. Yes (if app_directory subgroup is included)
app_directory.supported_languages An array of strings representing the languages supported by the app. Yes (if app_directory subgroup is included)
app_directory.pricing A string of pricing information. Yes (if app_directory subgroup is included)

Display

Field Description Required v1 v2
display_information A group of settings that describe parts of an app's appearance within Slack. If you're distributing the app via the Slack Marketplace, 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 when Slack displays information about your app. Can be 3-digit (#000) or 6-digit (#000000) hex values. Once a background color value is set, it cannot be removed, only updated. No

Features

Field Description Required v1 v2
features A group of settings corresponding to the Features section of an app's configuration 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.assistant_view Settings related to assistant view for app assistants. No
features.assistant_view.assistant_description A string description of the app assistant. Yes (if assistant_view subgroup is included)
features.assistant_view.suggested_prompts An array of hard-coded prompts for the app assistant container to prompt a user. Each object in the array contains a string title and string message property. 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 Legacy feature: An array of settings groups that describe workflow steps configuration. A maximum of 10 workflow steps can be included in this array. This feature has been deprecated. No
features.workflow_steps[].name Legacy feature: A string containing the name of the workflow step. Maximum length of 50 characters. This feature has been deprecated. Yes (for each workflow step included)
features.workflow_steps[].callback_id Legacy feature: A string containing the callback_id of the workflow step. Maximum length of 50 characters. This feature has been deprecated. Yes (for each workflow step included)

OAuth

Field Description Required v1 v2
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 be 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 be included in this array. No
oauth_config.token_management_enabled A boolean that indicates if token management should be enabled. No

Settings

Field Description Required v1 v2
settings A group of settings corresponding to the Settings section of an app's configuration pages. No
settings.allowed_ip_address_ranges An array of strings that contain IP addresses that conform to the Allowed IP Ranges feature. Maximum 10 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.event_subscriptions.metadata_subscriptions An array of objects that contain two required properties: a string app_id and a string event_type. No
settings.incoming_webhooks An object with a single boolean property, incoming_webhooks_enabled, that maps to Enabling incoming webhooks via your app settings. 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. This is required for functions. 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
settings.is_hosted A boolean that indicates if the app is hosted by Slack. No
settings.siws_links An object that indicates the use of SIWS Links. No
settings.siws_links.initiate_uri A string that follows the pattern ^https:\/\/ and indicates the URI. No
settings.function_runtime A string that indicates the runtime of any functions declared in the manifest. Possible values are remote for a self-hosted app or slack for an automation app. Yes (if using functions)

Functions

The function settings should be used to create custom workflow steps available for use in workflows either defined in the manifest or built directly in Workflow Builder.

The function property is a map, where the keys are the callback_id of the step. This callback_id can be any string, and is used to identify the individual steps in order to refer to them like functions.<callback_id>. Each step in the map contains all properties listed below.

Field Description Required v1 v2
functions.<callback_id> A unique string identifier in snake_case format representing the step; max 100 characters. No other steps in your application should share a callback ID. Changing a step's callback ID is not recommended, as the step will be removed from the app and created under the new callback ID, breaking anything referencing the old step. No
functions.<callback_id>.title A string to identify the step; max 255 characters. Yes (for each step included)
functions.<callback_id>.description A succinct summary of what your step does. Yes (for each step included)
functions.<callback_id>.input_parameters An object which describes one or more input parameters that will be available to your step. Each top-level property of this object defines the name of one input parameter available to your step. See details regarding structure below. Yes (for each step included)
functions.<callback_id>.output_parameters An object which describes one or more output parameters that will be returned by your step. Each top-level property of this object defines the name of one output parameter your step makes available. See details regarding structure below. Yes (for each step included)

The schema structure of input_parameters and output_parameters differs between version 1 and 2 of the app manifest. In version 1, input_parameters and output_parameters contain a list of parameters, with each parameter containing an is_required field, such that the structure looks like this:

functions:
  prep_ingredients:
    title: Prepare ingredients
    description: Runs sample function
    input_parameters:
      user_id:
        type: slack#/types/user_id
        title: User
        description: Message recipient
        is_required: true
        hint: Select a user in the workspace
        name: user_id
    output_parameters:
      user_id:
        type: slack#/types/user_id
        title: User
        description: User that completed the function
        is_required: true
        name: user_id

Whereas in the version 2 manifest, input_parameters and output_parameters contain a properties argument in which the parameters are nested alongside a required field denoting which properties are required. The structure looks like this:

functions:
  prep_ingredients:
    title: Prepare ingredients
    description: Runs sample function
    input_parameters:
      properties:
        user_id:
          type: slack#/types/user_id
          title: User
          description: Message recipient
          hint: Select a user in the workspace
          name: user_id
      required: { user_id }
    output_parameters:
      properties:
        user_id:
          type: slack#/types/user_id
          title: User
          description: User that completed the function
          name: user_id
      required: { user_id }

Workflows

Field Description Required v1 v2
workflows Declare the workflow the app provides. No
workflows.title String title of the workflow. Yes (if the workflows subgroup is included)
workflows.description String description of the workflow. Yes (if the workflows subgroup is included)
workflows.input_parameters An array of properties used as workflow inputs. No
workflows.output_parameters An array of properties used as workflow outputs. No
workflows.steps An array of step objects in the workflow. Each step contains a string id, a string function_id, an an object of inputs. If using a v2 manifest, an additonal property of type is available; its value can be one of the following: function, switch, or conditional. Yes (if the workflows subgroup is included)
workflows.suggested_triggers An array of trigger objects. Each trigger object contains a string name, a string description, string type, and an object array of inputs. No

Datastores

Field Description Required v1 v2
datastores Declares the datastores used by the app. No
datastores.primary_key A unique string. Yes (for each datastore included)
datastores.attributes An object of datastore attributes. Yes (for each datastore included)
datastores.attributes.type A string representing the object type of the attribute. Yes (for each datastore included)
datastores.attributes.items An object with two properties: a required string type and properties, which is an array of strings. No
datastores.attributes.properties An object array of properties. No
datastores.time_to_live_attribute A string that represents the time to live attribute. See Delete items automatically in the datastore documentation for more information. No

Outgoing domains

Field Description Required v1 v2
outgoing_domains An array of accepted egress domains for an app with function_runtime = slack. Each string item must follow the pattern ^(?![\.\-])([-a-zA-Z0-9\.])+([a-zA-Z0-9])$. Max 10 items. No

Types

Field Description Required v1 v2
types Declare the types the app provides. Max 50. No
types.type String type. Yes (for each type provided)
types.title String title of the type. No
types.description String description of the type. No
types.is_required Boolean indicating if the type is required. No
types.is_hidden Boolean indicating if the type is hidden. No
types.hint String hint for the type. No

Events

Field Description Required v1 v2
metadata_events Declare the events the app can emit. Can either be an object or a reference. No
metadata_events.object.type Type of event. Object containing three properties: string type, object enum, and string title. Yes (if metadata_events subgroup is included)
metadata_events.object.title The string title of the event. No
metadata_events.object.description The string description of the event. No
metadata_events.object.default One of the following: string, integer, number, boolean, array. No
metadata_events.object.examples Array of example items. Items can be the following: string, integer, number, boolean, array. No
metadata_events.object.required An array of required objects. No
metadata_events.object.additionalProperties A boolean that indicates if there are additional properties. No
metadata_events.object.nullable A boolean indicating if the object is nullable. No
metadata_events.object.properties An object of properties, max 50, of the following: reference, channel_id, user_id, user_email, user_permission, usergroup_id, timestamp, string, integer, number, user_context, interactivity, boolean, array, oauth2, rich_text, expanded_rich_text, blocks, date, form_input_object, form_input, message_context, message_ts, list_id, canvas_id, canvas_template_id, channel_canvas_id, currency, team_id. No
metadata_events.object.is_required A boolean indicating if the object is required. No
metadata_events.object.is_hidden A boolean indicating if the object is hidden. No
metadata_events.object.hint A string hint for the object. No
metadata_events.object.choices An array of enum choices. No
metadata_events.object.choices.items.value One of the following: string, number, object. Yes (if metadata_events.object.choices subgroup is included)
metadata_events.object.choices.items.title String title. Yes (if metadata_events.object.choices subgroup is included)
metadata_events.object.choices.items.description String description. No
metadata_events.object.choices.items.is_hidden Boolean flag indicating if the choice is hidden. No
metadata_events.object.choices.items.hint A string hint. No
metadata_events.object.render_condition A render condition object. No
metadata_events.object.render_condition.operator A string logical operator which acts on the conditions. Yes (if metadata_events.object.render_condition subgroup is included)
metadata_events.object.render_condition.is_required Specifies whether the parameter is required, if render conditions evaluate to true. No
metadata_events.object.render_condition.conditions An array of conditions which specify if the field should be rendered or now. Yes (if metadata_events.object.render_condition subgroup is included)
metadata_events.reference.type User-defined string type reference that adheres to the pattern ^(?!slack)(\w*#)\/(\w+)\/(\w+)$. Yes (if metadata_events.reference subgroup is included)
metadata_events.reference.title A string title of the event. No
metadata_events.reference.description A string description of the event. No
metadata_events.reference.default One of the following: string, number, integer, boolean, object, array. No
metadata_events.reference.examples An array of examples; max 10. The items can be one of the following: string, number, integer, boolean, object, array. No
metadata_events.reference.nullable Boolean flag indicating if the event is nullable. No
metadata_events.reference.is_required Boolean flag indicating if the event is required. No
metadata_events.reference.is_hidden Boolean flag indicating if the event is hidden. No
metadata_events.reference.hint A string hint for the event. No

External auth providers

Field Description Required v1 v2
external_auth_providers Declares the OAuth configuration used by the app. No
external_auth_providers.provider_type Can be either CUSTOM or SLACK_PROVIDED. Yes (if the external_auth_providers subgroup is provided)
external_auth_providers.options If provider_type is SLACK_PROVIDED, the object will contain a string client_id and string scope. If the provider_type is CUSTOM, the object will contain a client_id, provider_name, authorization_url, token_url, scope, identity_config, authorization_url_extras, use_pkce, and token_url_config. Yes (if the external_auth_providers subgroup is provided)
external_auth_providers.options.client_id String, max 1024 characters. Yes (if the external_auth_providers subgroup is provided)
external_auth_providers.options.provider_name String, max 255 characters. Yes (if provider_type is CUSTOM)
external_auth_providers.options.authorization_url String, max 255 characters. Must follow the pattern ^https:\/\/. Yes (if provider_type is CUSTOM)
external_auth_providers.options.token_url String, max 255 characters. Must follow the pattern ^https:\/\/. Yes (if provider_type is CUSTOM)
external_auth_providers.options.scope String array of scopes. Yes (if the external_auth_providers subgroup is provided)
external_auth_providers.options.authorization_url_extras Object of extras configurations. No
external_auth_providers.options.identity_config Identity configuration object. See identity config object for fields. Yes (if provider_type is CUSTOM)
external_auth_providers.options.use_pkce Boolean flag indicating if this provider uses PKCE. No
external_auth_providers.options.token_url_config An object with one boolean value, use_basic_auth_scheme. No

The identity_config object

Field Description Required v1 v2
url String, min length of 5 and max of 255. Must follow pattern ^https:\/\/. Yes (if the external_auth_providers subgroup is provided)
account_identifier String, min length of 1 and max of 255. Must follow pattern ^https:\/\/. Yes (if the external_auth_providers subgroup is provided)
headers An object of headers. No
body An object of the request body. No
http_method_type Can be either GET or POST. No

Compliance

Field Description Required v1 v2
compliance Compliance certifications for GovSlack. No
compliance.fedramp_authorization String; FedRAMP certification. No
compliance.dod_srg_ilx String; Department of Defense (DoD) Cloud Computing Security Requirements Guide (SRG). No
compliance.itar_compliant String; ITAR compliance. No