Reference: composition objects

Composition objects can be used inside of block elements and certain message payload fields. They are common JSON object patterns that you'll encounter frequently when building blocks or composing messages.

The lists of fields and values below describe the JSON that apps can use to generate each object.


Confirmation dialog object

Defines a dialog that adds a confirmation step to interactive elements.

An object that defines a dialog that provides a confirmation step to any interactive element. This dialog will ask the user to confirm their action by offering a confirm and deny buttons.

Fields

Field Type Description Required?
title Object A plain_text text object that defines the dialog's title. Maximum length for this field is 100 characters. Yes
text Object A plain_text text object that defines the explanatory text that appears in the confirm dialog. Maximum length for the text in this field is 300 characters. Yes
confirm Object A plain_text text object to define the text of the button that confirms the action. Maximum length for the text in this field is 30 characters. Yes
deny Object A plain_text text object to define the text of the button that cancels the action. Maximum length for the text in this field is 30 characters. Yes
style String Defines the color scheme applied to the confirm button. A value of danger will display the button with a red background on desktop, or red text on mobile. A value of primary will display the button with a green background on desktop, or blue text on mobile. If this field is not provided, the default value will be primary. No

Example

{
    "title": {
        "type": "plain_text",
        "text": "Are you sure?"
    },
    "text": {
        "type": "plain_text",
        "text": "Wouldn't you prefer a good game of chess?"
    },
    "confirm": {
        "type": "plain_text",
        "text": "Do it"
    },
    "deny": {
        "type": "plain_text",
        "text": "Stop, I've changed my mind!"
    }
}

View an example


Conversation filter object

Defines a filter for the list of options in a conversation selector menu.

The menu can be either a conversations select menu or a conversations multi-select menu.

Fields

Field Type Description Required?
include String[] Indicates which type of conversations should be included in the list. When this field is provided, any conversations that do not match will be excluded

You should provide an array of strings from the following options: im, mpim, private, and public. The array cannot be empty.
No
exclude_external_shared_channels Boolean Indicates whether to exclude external shared channels from conversation lists. This field will not exclude users from shared channels. Defaults to false. No
exclude_bot_users Boolean Indicates whether to exclude bot users from conversation lists. Defaults to false. No

Please note that while none of the fields above are individually required, you must supply at least one of these fields.

Example

{
    "type": "conversations_select",
    "placeholder": {
        "type": "plain_text",
        "text": "Select a conversation",
        "emoji": true
    },
    "filter": {
        "include": [
            "public",
            "mpim"
        ],
        "exclude_bot_users": true
    }
}

View an example

Known issues

  • In iOS, the placeholder text is replaced with "0 selected" when there are no selected conversations.

  • In iOS, there are UI inconsistencies when users select items in multi-select menus.


Dispatch action configuration object

Defines when a plain-text input element will return a block_actions interaction payload.

Fields

Field Type Description Required?
trigger_actions_on String[] An array of interaction types that you would like to receive a block_actions payload for. Should be one or both of:

on_enter_pressed — payload is dispatched when user presses the enter key while the input is in focus. Hint text will appear underneath the input explaining to the user to press enter to submit.

on_character_entered — payload is dispatched when a character is entered (or removed) in the input.
No

Example

{
    "type": "input",
    "dispatch_action": true,
    "element": {
        "type": "plain_text_input",
        "multiline": true,
        "dispatch_action_config": {
            "trigger_actions_on": [
                "on_character_entered"
            ]
        }
    },
    "label": {
        "type": "plain_text",
        "text": "This is a multiline plain-text input",
        "emoji": true
    }
}

Option object

Defines a single item in a number of item selection elements.

An object that represents a single selectable item in a select menu, multi-select menu, checkbox group, radio button group, or overflow menu.

Fields

Field Type Description Required?
text Object A text object that defines the text shown in the option on the menu. Overflow, select, and multi-select menus can only use plain_text objects, while radio buttons and checkboxes can use mrkdwn text objects. Maximum length for the text in this field is 75 characters. Yes
value String A unique string value that will be passed to your app when this option is chosen. Maximum length for this field is 150 characters. Yes
description Object A plain_text text object that defines a line of descriptive text shown below the text field beside a single selectable item in a select menu, multi-select menu, checkbox group, radio button group, or overflow menu. Checkbox group and radio button group items can also use mrkdwn formatting. Maximum length for the text within this field is 75 characters. No
url String A URL to load in the user's browser when the option is clicked. The url attribute is only available in overflow menus. Maximum length for this field is 3000 characters. If you're using url, you'll still receive an interaction payload and will need to send an acknowledgement response. No

Example

{
    "text": {
        "type": "plain_text",
        "text": "Maru"
    },
    "value": "maru"
}

View an example


Option group object

Defines a way to group options in a menu.

The menu can be a select menu or a multi-select menu. An option_groups array can have a maximum number of 100 option groups with a maximum of 100 options.

Fields

Field Type Description Required?
label Object A plain_text text object that defines the label shown above this group of options. Maximum length for the text in this field is 75 characters. Yes
options Object[] An array of option objects that belong to this specific group. Maximum of 100 items. Yes

Example

"option_groups": [
    {
        "label": {
            "type": "plain_text",
            "text": "Group 1"
        },
        "options": [
            {
                "text": {
                    "type": "plain_text",
                    "text": "*this is plain_text text*"
                },
                "value": "value-0"
            },
            {
                "text": {
                    "type": "plain_text",
                    "text": "*this is plain_text text*"
                },
                "value": "value-1"
            },
            {
                "text": {
                    "type": "plain_text",
                    "text": "*this is plain_text text*"
                },
                "value": "value-2"
            }
        ]
    },
    {
        "label": {
            "type": "plain_text",
            "text": "Group 2"
        },
        "options": [
            {
                "text": {
                    "type": "plain_text",
                    "text": "*this is plain_text text*"
                },
                "value": "value-3"
            }
        ]
    }
]

View an example


Text object

Defines an object containing some text.

Formatted either as plain_text or using mrkdwn, our proprietary contribution to the much beloved Markdown standard.

Fields

Field Type Description Required?
type String The formatting to use for this text object. Can be one of plain_textor mrkdwn. Yes
text String The text for the block. This field accepts any of the standard text formatting markup when type is mrkdwn. The minimum length is 1 and maximum length is 3000 characters. Yes
emoji Boolean Indicates whether emojis in a text field should be escaped into the colon emoji format. This field is only usable when type is plain_text. No
verbatim Boolean When set to false (as is default) URLs will be auto-converted into links, conversation names will be link-ified, and certain mentions will be automatically parsed.
When set to true, Slack will continue to process all markdown formatting and manual parsing strings, but it won’t modify any plain-text content. For example, channel names will not be hyperlinked. This field is only usable when type is mrkdwn.

Example

{
    "type": "mrkdwn",
    "text": "A message *with some bold text* and _some italicized text_."
}

View an example


Trigger object

Defines an object containing trigger information.

Fields

Field Type Description Required?
url String A link trigger URL. Must be associated with a valid trigger. Yes
customizable_input_parameters Object[] An array of input parameter objects. Each specified name must match an input parameter defined on the workflow of the provided trigger (url), and the input parameter mapping on the trigger must be set as customizable: true. Each specified value must match the type defined by the workflow input parameter of the matching name. No

The values used for these customizable_input_parameters may be visible client-side to end users. You should not share sensitive information or secrets via these input parameters.

Example

{
  "url": "https://slack.com/shortcuts/Ft0123ABC456/123...xyz",
  "customizable_input_parameters": [
    {
      "name": "input_parameter_a",
      "value": "Value for input param A"
    },
    {
      "name": "input_parameter_b",
      "value": "Value for input param B"
    }
  ]
}

Workflow object

Defines an object containing workflow information.

Fields

Field Type Description Required?
trigger Object A trigger object that contains information about a workflow's trigger. Yes

Example

{
  "trigger": {
      "url": "https://slack.com/shortcuts/Ft0123ABC456/321...zyx",
      "customizable_input_parameters": [
        {
          "name": "input_parameter_a",
          "value": "Value for input param A"
        },
        {
          "name": "input_parameter_b",
          "value": "Value for input param B"
        }
      ]
  }
}

Slack file object

Defines an object containing Slack file information to be used in an image block or image element.

This file must be an image and you must provide either the URL or ID. In addition, the user posting these blocks must have access to this file. If both are provided then the payload will be rejected. Currently only png, jpg, jpeg, and gif Slack image files are supported.

Fields

Field Type Description Required?
url string This URL can be the url_private or the permalink of the Slack file. No
id string Slack ID of the file. No

Example

{
  "slack_file": {
      "url": "https://files.slack.com/files-pri/T0123456-F0123456/xyz.png",
  }
}
{
  "slack_file": {
      "id": "F0123456",
  }
}