App manifest reference

Welcome to the new home of Slack developer docs!

We're still building and not all features are available quite yet. Enjoy this peek into the future!

Not ready for the future? Return to the past at api.slack.com.

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.

YAML

_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

JSON

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

TypeScript

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.
 */
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#/reference/objects/user-object_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#/reference/objects/user-object_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#/reference/objects/user-object_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#/reference/objects/user-object_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	✅	✅