Skip to main content

App manifest reference

Manifests are written in YAML or JSON using a specific structure. The 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: The Very Fantastic Name of Your App 
 long_description: A very long description. The minimum length is 174 characters and the maximum length is 4,000 characters. The app manifest in App Settings throws an error if it is less than 174 characters. 
 description: A shorter description. 
 background_color: "#0000AA" 
settings: 
 allowed_ip_address_ranges: 
   - 123.123.123.123
   - 124.124.124.124
 org_deploy_enabled: false 
 socket_mode_enabled: false 
 token_rotation_enabled: false 
 event_subscriptions: 
   request_url: https://example.com/slack/the_Events_API_request_URL 
   bot_events: 
     - app_home_opened
     - message_metadata_deleted
     - link_shared
     - assistant_thread_started
     - message.im
     - function_executed
   user_events: 
     - reaction_added
   metadata_subscriptions: 
     - app_id: A81FQ3116
       event_type: star_added
     - app_id: A123ABC456
       event_type: star_removed
     - app_id: '*' 
       event_type: task_added
 incoming_webhooks:
   incoming_webhooks_enabled: false 
 interactivity: 
   is_enabled: true 
   request_url: https://example.com/slack/message_action 
   message_menu_options_url: https://example.com/slack/message_menu_options 
 is_hosted: false 
 function_runtime: remote )
features: 
 app_home: 
   home_tab_enabled: false 
   messages_tab_enabled: false 
   messages_tab_read_only_enabled: false 
 assistant_view:
   assistant_description: this is a string description of the app assistant. What does your assistant do?
   suggested_prompts:
     - title: User help
       message: How do I use this awesome app?
 bot_user:
   display_name: Your Amazingly Helpful Bot
   always_online: false
 shortcuts:
   - name: Use your app
     callback_id: a-really-cool-callback_id
     description: Awesome and Helpful App
     type: message
 slash_commands:
   - command: /z
     description: You see a mailbox in the field.
     should_escape: false
     usage_hint: /zork open mailbox
     url: https://example.com/slack/slash/please
 unfurl_domains:
   - example.com
oauth_config:
 scopes: 
   bot: 
     - commands
     - chat:write
     - chat:write.public
     - metadata.message:read
     - links:read
     - assistant:write
     - im:history
     - reactions:write
   user: 
     - channels:history
     - reactions:read
     - reactions:write
 redirect_urls: 
   - https://example.com/slack/auth
 token_management_enabled: true
functions:
 a_callback_id:
   title: A Callback ID
   description: This is an example callback id! Huzzah!
   input_parameters:
     properties:
       user_id:
         type: string
         title: User
         description: Message recipient
         is_required: true
         hint: Select a user in the workspace
         name: user_id
     required:
       - user_id
   output_parameters:
     properties:
       user_id:
         type: string
         title: User
         description: User that completed the function
         is_required: true
         name: user_id
     required:
       - user_id
workflows:
 cool_name_for_a_workflow:
   title: Name your workflow
   description: Describe your workflow here
   input_parameters:
     properties:
       channel_id_for_workflow:
         type: slack#/types/channel_id
       first_property:
         type: string
       second_property:
         type: string
       third_property:
         type: string
     required:
       - channel_id_for_workflow
       - first_property
       - second_property
       - third_property
   steps:
     - id: "0"
       function_id: slack#/functions/send_message
       inputs:
         channel_id: "{{inputs.channel_id_for_workflow}}"
         message: "This is the message you'll send to your users :yay: You can put your {{inputs.first_property}} {{inputs.second_property}}, {{inputs.third_property}} here!"
         interactive_blocks:
           - type: actions
             elements:
               - type: button
                 text:
                   type: plain_text
                   text: Share
                 action_id: share
     - id: "1"
       function_id: slack#/functions/open_form
       inputs:
         title: Title for your 2nd step
         interactivity: "{{steps.0.interactivity}}"
         submit_label: Share
         fields:
           elements:
             - name: announcement_channel
               title: Select an announcements channel
               type: slack#/types/channel_id
           required:
             - announcement_channel
     - id: "2"
       function_id: slack#/functions/send_message
       inputs:
         channel_id: "{{steps.1.fields.announcement_channel}}"
         message: |-
           The properties you defined in your inputs section can also be used in the steps {{inputs.second_property}}  :rocket:
          ```{{inputs.channel_id_for_workflow}}```
     - id: "3"
       function_id: slack#/functions/add_reaction
       inputs:
         message_context: "{{steps.2.message_context}}"
         emoji: tada
   suggested_triggers:
     send_a_message:
       name: Send a message
       description: Sends a message for you
       type: string
       inputs:
         channel_id:
           value: channel_id_for_workflow
         other_customizable_param:
           value: this is cool right?
outgoing_domains:
 - anoutgoing.domain
 - anotheroutgoing.domain
types:
 your_shiny_custom_type:
   title: "your_shiny_custom_type"
   type: object
   description: Describe what very cool stuff this type does in your app
   is_required: false
   is_hidden: false
   hint: give a hint for the future folks who use this


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

Metadata​

FieldDescriptionRequiredv1v2
_metadataA group of settings that describe the manifest.No✅✅
_metadata.major_versionAn integer that specifies the major version of the manifest schema to target.No✅✅
_metadata.minor_versionAn 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.

FieldDescriptionRequiredv1v2
app_directoryAn object containing information to be listed in the Slack Marketplace.No✅✅
app_directory.app_directory_categoriesAn array of strings.No✅✅
app_directory.use_direct_installBoolean value if the app should use direct install.No✅✅
app_directory.direct_install_urlA string URL of the install page, following the pattern ^https?:\/\/.No✅✅
app_directory.installation_landing_pageA string URL of the installation landing page, following the pattern ^https?:\/\/.Yes (if app_directory subgroup is included)✅✅
app_directory.privacy_policy_urlA link to your app's privacy policy.Yes (if app_directory subgroup is included)✅✅
app_directory.support_urlA link to your app's support URL.Yes (if app_directory subgroup is included)✅✅
app_directory.support_emailAn email address to contact your app's support.Yes (if app_directory subgroup is included)✅✅
app_directory.supported_languagesAn array of strings representing the languages supported by the app.Yes (if app_directory subgroup is included)✅✅
app_directory.pricingA string of pricing information.Yes (if app_directory subgroup is included)✅✅

Display​

FieldDescriptionRequiredv1v2
display_informationA 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.nameA string of the name of the app. Maximum length is 35 characters.Yes✅✅
display_information.descriptionA string with a short description of the app for display to users. Maximum length is 140 characters.No✅✅
display_information.long_descriptionA string with a longer version of the description of the app. Maximum length is 4000 characters.No✅✅
display_information.background_colorA 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​

FieldDescriptionRequiredv1v2
featuresA group of settings corresponding to the Features section of an app's configuration pages.No✅✅
features.app_homeA subgroup of settings that describe App Home configuration.No✅✅
features.app_home.home_tab_enabledA boolean that specifies whether or not the Home tab is enabled.No✅✅
features.app_home.messages_tab_enabledA boolean that specifies whether or not the Messages tab in your App Home is enabled.No✅✅
features.app_home.messages_tab_read_only_enabledA 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_viewSettings related to assistant view for apps using AI features.No✅✅
features.assistant_view.assistant_descriptionA string description of the app assistant.Yes (if assistant_view subgroup is included)✅✅
features.assistant_view.suggested_promptsAn 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_userA subgroup of settings that describe bot user configuration.No✅✅
features.bot_user.display_nameA 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_onlineA boolean that specifies whether or not the bot user will always appear to be online.No✅✅
features.rich_previewsA subgroup of settings that describe rich previews configuration.No✅✅
features.rich_previews.is_activeA boolean that specifies whether or not rich previews are enabled.No✅✅
features.rich_previews.entity_typesAn array of strings containing entity types for rich previews.No✅✅
features.shortcutsAn array of settings groups that describe shortcuts configuration. A maximum of 10 shortcuts can be included in this array.No✅✅
features.shortcuts[].nameA string containing the name of the shortcut.Yes (for each shortcut included)✅✅
features.shortcuts[].callback_idA string containing the callback_id of this shortcut. Maximum length is 255 characters.Yes (for each shortcut included)✅✅
features.shortcuts[].descriptionA string containing a short description of this shortcut. Maximum length is 150 characters.Yes (for each shortcut included)✅✅
features.shortcuts[].typeA string containing one of message or global. This specifies which type of shortcut is being described.Yes (for each shortcut included)✅✅
features.slash_commandsAn 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[].commandA 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[].descriptionA 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_escapeA 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[].urlA string containing the full https URL that acts as the slash command's request URL.No✅✅
features.slash_commands[].usage_hintA string hint about how to use the slash command for users. Maximum length is 1000 characters.No✅✅
features.unfurl_domainsAn 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_stepsLegacy 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[].nameLegacy 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_idLegacy 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​

FieldDescriptionRequiredv1v2
oauth_configA group of settings describing OAuth configuration for the app.No✅✅
oauth_config.redirect_urlsAn array of strings containing OAuth redirect URLs. A maximum of 1000 redirect URLs can be included in this array.No✅✅
oauth_config.scopesA subgroup of settings that describe permission scopes configuration.No✅✅
oauth_config.scopes.botAn 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.userAn 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_enabledA boolean that indicates if token management should be enabled.No✅✅

Settings​

FieldDescriptionRequiredv1v2
settingsA group of settings corresponding to the Settings section of an app's configuration pages.No✅✅
settings.allowed_ip_address_rangesAn array of strings that contain IP addresses that conform to the Allowed IP Ranges feature. Maximum 10 items.No✅✅
settings.event_subscriptionsA subgroup of settings that describe Events API configuration for the app.No✅✅
settings.event_subscriptions.request_urlA 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_eventsAn 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_eventsAn 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_subscriptionsAn array of objects that contain two required properties: a string app_id and a string event_type.No✅✅
settings.incoming_webhooksAn object with a single boolean property, incoming_webhooks_enabled, that maps to Enabling incoming webhooks via your app settings.No✅✅
settings.interactivityA subgroup of settings that describe interactivity configuration for the app.No✅✅
settings.interactivity.is_enabledA boolean that specifies whether or not interactivity features are enabled.Yes (if using interactivity settings)✅✅
settings.interactivity.request_urlA string containing the full https URL that acts as the interactive Request URL.No✅✅
settings.interactivity.message_menu_options_urlA string containing the full https URL that acts as the interactive Options Load URL.No✅✅
settings.org_deploy_enabledA boolean that specifies whether or not organization-wide deployment is enabled. This is required for functions.No✅✅
settings.socket_mode_enabledA boolean that specifies whether or not Socket Mode is enabled.No✅✅
settings.token_rotation_enabledA boolean that specifies whether or not token rotation is enabled.No✅✅
settings.is_hostedA boolean that indicates if the app is hosted by Slack.No✅✅
settings.siws_linksAn object that indicates the use of SIWS Links.No✅✅
settings.siws_links.initiate_uriA string that follows the pattern ^https:\/\/ and indicates the URI.No✅✅
settings.function_runtimeA 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 app built with the Deno Slack SDK.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.

FieldDescriptionRequiredv1v2
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>.titleA string to identify the step; max 255 characters.Yes (for each step included)✅✅
functions.<callback_id>.descriptionA succinct summary of what your step does.Yes (for each step included)✅✅
functions.<callback_id>.input_parametersAn 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_parametersAn 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​

FieldDescriptionRequiredv1v2
workflowsDeclare the workflow the app provides.No✅✅
workflows.titleString title of the workflow.Yes (if the workflows subgroup is included)✅✅
workflows.descriptionString description of the workflow.Yes (if the workflows subgroup is included)✅✅
workflows.input_parametersAn array of properties used as workflow inputs.No✅✅
workflows.output_parametersAn array of properties used as workflow outputs.No✅✅
workflows.stepsAn 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 additional 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_triggersAn array of trigger objects. Each trigger object contains a string name, a string description, string type, and an object array of inputs.No✅✅

Datastores​

FieldDescriptionRequiredv1v2
datastoresDeclares the datastores used by the app.No✅✅
datastores.primary_keyA unique string.Yes (for each datastore included)✅✅
datastores.attributesAn object of datastore attributes.Yes (for each datastore included)✅✅
datastores.attributes.typeA string representing the object type of the attribute.Yes (for each datastore included)✅✅
datastores.attributes.itemsAn object with two properties: a required string type and properties, which is an array of strings.No✅✅
datastores.attributes.propertiesAn object array of properties.No✅✅
datastores.time_to_live_attributeA string that represents the time to live attribute. See Delete items automatically in the datastore documentation for more information.No✅✅

Outgoing domains​

FieldDescriptionRequiredv1v2
outgoing_domainsAn 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​

FieldDescriptionRequiredv1v2
typesDeclare the types the app provides. Max 50.No✅✅
types.typeString type.Yes (for each type provided)✅✅
types.titleString title of the type.No✅✅
types.descriptionString description of the type.No✅✅
types.is_requiredBoolean indicating if the type is required.No✅✅
types.is_hiddenBoolean indicating if the type is hidden.No✅✅
types.hintString hint for the type.No✅✅

Events​

FieldDescriptionRequiredv1v2
metadata_eventsDeclare the events the app can emit. Can either be an object or a reference.No✅✅
metadata_events.object.typeType of event. Object containing three properties: string type, object enum, and string title.Yes (if metadata_events subgroup is included)✅✅
metadata_events.object.titleThe string title of the event.No✅✅
metadata_events.object.descriptionThe string description of the event.No✅✅
metadata_events.object.defaultOne of the following: string, integer, number, boolean, array.No✅✅
metadata_events.object.examplesArray of example items. Items can be the following: string, integer, number, boolean, array.No✅✅
metadata_events.object.requiredAn array of required objects.No✅✅
metadata_events.object.additionalPropertiesA boolean that indicates if there are additional properties.No✅✅
metadata_events.object.nullableA boolean indicating if the object is nullable.No✅✅
metadata_events.object.propertiesAn 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_requiredA boolean indicating if the object is required.No✅✅
metadata_events.object.is_hiddenA boolean indicating if the object is hidden.No✅✅
metadata_events.object.hintA string hint for the object.No✅✅
metadata_events.object.choicesAn array of enum choices.No✅✅
metadata_events.object.choices.items.valueOne of the following: string, number, object.Yes (if metadata_events.object.choices subgroup is included)✅✅
metadata_events.object.choices.items.titleString title.Yes (if metadata_events.object.choices subgroup is included)✅✅
metadata_events.object.choices.items.descriptionString description.No✅✅
metadata_events.object.choices.items.is_hiddenBoolean flag indicating if the choice is hidden.No✅✅
metadata_events.object.choices.items.hintA string hint.No✅✅
metadata_events.object.render_conditionA render condition object.No✅✅
metadata_events.object.render_condition.operatorA string logical operator which acts on the conditions.Yes (if metadata_events.object.render_condition subgroup is included)✅✅
metadata_events.object.render_condition.is_requiredSpecifies whether the parameter is required, if render conditions evaluate to true.No✅✅
metadata_events.object.render_condition.conditionsAn 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.typeUser-defined string type reference that adheres to the pattern ^(?!slack)(\w*#)\/(\w+)\/(\w+)$.Yes (if metadata_events.reference subgroup is included)✅✅
metadata_events.reference.titleA string title of the event.No✅✅
metadata_events.reference.descriptionA string description of the event.No✅✅
metadata_events.reference.defaultOne of the following: string, number, integer, boolean, object, array.No✅✅
metadata_events.reference.examplesAn array of examples; max 10. The items can be one of the following: string, number, integer, boolean, object, array.No✅✅
metadata_events.reference.nullableBoolean flag indicating if the event is nullable.No✅✅
metadata_events.reference.is_requiredBoolean flag indicating if the event is required.No✅✅
metadata_events.reference.is_hiddenBoolean flag indicating if the event is hidden.No✅✅
metadata_events.reference.hintA string hint for the event.No✅✅

External auth providers​

FieldDescriptionRequiredv1v2
external_auth_providersDeclares the OAuth configuration used by the app.No✅✅
external_auth_providers.provider_typeCan be either CUSTOM or SLACK_PROVIDED.Yes (if the external_auth_providers subgroup is provided)✅✅
external_auth_providers.optionsIf 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_idString, max 1024 characters.Yes (if the external_auth_providers subgroup is provided)✅✅
external_auth_providers.options.provider_nameString, max 255 characters.Yes (if provider_type is CUSTOM)✅✅
external_auth_providers.options.authorization_urlString, max 255 characters. Must follow the pattern ^https:\/\/.Yes (if provider_type is CUSTOM)✅✅
external_auth_providers.options.token_urlString, max 255 characters. Must follow the pattern ^https:\/\/.Yes (if provider_type is CUSTOM)✅✅
external_auth_providers.options.scopeString array of scopes.Yes (if the external_auth_providers subgroup is provided)✅✅
external_auth_providers.options.authorization_url_extrasObject of extras configurations.No✅✅
external_auth_providers.options.identity_configIdentity configuration object. See identity config object for fields.Yes (if provider_type is CUSTOM)✅✅
external_auth_providers.options.use_pkceBoolean flag indicating if this provider uses PKCE.No✅✅
external_auth_providers.options.token_url_configAn object with one boolean value, use_basic_auth_scheme.No✅✅

The identity_config object​

FieldDescriptionRequiredv1v2
urlString, min length of 5 and max of 255. Must follow pattern ^https:\/\/.Yes (if the external_auth_providers subgroup is provided)✅✅
account_identifierString, min length of 1 and max of 255. Must follow pattern ^https:\/\/.Yes (if the external_auth_providers subgroup is provided)✅✅
headersAn object of headers.No✅✅
bodyAn object of the request body.No✅✅
http_method_typeCan be either GET or POST.No✅✅

Compliance​

FieldDescriptionRequiredv1v2
complianceCompliance certifications for GovSlack.No✅✅
compliance.fedramp_authorizationString; FedRAMP certification.No✅✅
compliance.dod_srg_ilxString; Department of Defense (DoD) Cloud Computing Security Requirements Guide (SRG).No✅✅
compliance.itar_compliantString; ITAR compliance.No✅✅