Reference: Block suggestion payloads

A block_suggestion payload is received when a user interacts with a select menu of external data source element. Users may return a maximum of 100 options or option groups when handling the block_suggestion payload.

Read our guide to handling payloads from user interactions to learn how your app should process and respond to these payloads.

Properties

This is a list of the properties that can be encountered in this type of interaction payload:

Properties received in a block_suggestion event may differ based on the source of the interactive elementsβ€”a modal view, message, or home tab surface. A check in the column means that property is included in a block_suggestion event sent to a function, a non-function, or both. Functions refer to workflow apps; refer to Block Kit Interactivity for more information.

Property Functions Non-Functions Description Required?
user βœ“ βœ“ Details for the user that initiated the block suggestion interaction. The user.team_id will report an enterprise organization ID (which starts with an E) instead of team ID (which starts with a T), when using Enterprise Grid. Yes
team βœ“ βœ“ The workspace, or team, details the Block Kit interaction originated from. In the case of Enterprise Grid, team can also have the properties enterprise_id and enterprise_name, which represent the ID and the name of the grid, respectively. Yes
api_app_id βœ“ βœ“ The encoded application ID the event was dispatched to, e.g. A123456. Yes
block_id βœ“ βœ“ Identifies the block within a surface that contained the interactive component that was used. See the reference guide for the block you're using for more info on the block_id field. Yes
action_id βœ“ βœ“ Identifies the interactive component itself. Some blocks can contain multiple interactive components, so the block_id alone may not be specific enough to identify the source component. See the reference guide for the interactive element you're using for more info on the action_id field. Yes
function_data βœ“ Metadata about the function execution that generated the block where this block suggestion took place. Yes
bot_access_token βœ“ A workflow (just-in-time) token generated for this block suggestion. Yes
enterprise βœ“ βœ“ The enterprise the installed app is part of, if the app is either workspace-installed on an org, or org-installed. No
channel βœ“ βœ“ The channel the block suggestion interaction originated from. No
message βœ“ βœ“ The message where this block suggestion took place, if the block was contained in a message. No
view βœ“ βœ“ The view where this block suggestion took place, if the block was contained in a view. No
value βœ“ βœ“ The value the user entered into the select menu. Yes

Examples

A payload from a block suggestion component used in a modal view:

{
  "type": "block_suggestion",
  "team": {
    "id": "ABC123DEF45",
    "domain": "workspace"
  },
  "enterprise": null,
  "user": {
    "id": "EXAMPLE1234",
    "name": "sallyslack",
    "team_id": "ABC123DEF45"
  },
  "view": {
    "id": "DEFGHIJ89101",
    "team_id": "ABC123DEF45",
    "app_id": "APPID6789101",
    "app_installed_team_id": "ABC123DEF45",
    "bot_id": "BOTSRCOOL12",
    "title": {
      "type": "plain_text",
      "text": "Deny Request",
      "emoji": true
    },
    "type": "modal",
    "blocks": [
      /* ... your view blocks here */
    ],
    "close": null,
    "submit": {
      "type": "plain_text",
      "text": "Next",
      "emoji": true
    },
    "state": {
      "values": {}
    },
    "hash": "1695235327.610lSjjQ",
    "private_metadata": "{\"messageTS\":\"1695235212.424669\"}",
    "callback_id": "deny_modal_main",
    "root_view_id": "DEFGHIJ89101",
    "previous_view_id": null,
    "clear_on_close": false,
    "notify_on_close": true,
    "external_id": ""
  },
  "container": {
    "type": "view",
    "view_id": "DEFGHIJ89101"
  },
  "api_app_id": "APPID6789101",
  "action_id": "ext_select_input",
  "block_id": "ext_select_block",
  "value": "tech",
  "function_data": {
    "execution_id": "EXECUTEF9101",
    "function": {
      "callback_id": "review_approval"
    },
    "inputs": {
      "details": "test",
      "subject": "test",
      "requester_id": "EXAMPLE1234",
      "approval_channel_id": "APPROVE1234"
    }
  },
  "bot_access_token": "xwfp-2335208212870-2354592155553-5925491402867-c2a66a8fb377b19e0d8f6c8d24af530d"
}

A payload from suggestion component used in a message from a workspace using Enterprise Grid:

{
    "type": "block_suggestion",
    "user": {
        "id": "ABCDE6789",
        "username": "harry-potter",
        "name": "harry-potter",
        "team_id": "ENT4567"
    },
    "container": {
        "type": "message",
        "message_ts": "1628851405.000300",
        "channel_id": "CHAN56789",
        "is_ephemeral": false
    },
    "api_app_id": "APP876543",
    "token": "XAg1RqiO8jaSczkIQpxq7Z4o",
    "action_id": "location_select-action",
    "block_id": "bK6",
    "value": "test",
    "team": {
        "id": "ENT4567",
        "domain": "my-gridworkspace",
        "enterprise_id": "ENT123789",
        "enterprise_name": "my-enterprise"
    },
    "enterprise": {
        "id": "ENT123789",
        "name": "my-enterprise"
    },
    "is_enterprise_install": false,
    "channel": {
        "id": "CHAN56789",
        "name": "channel-team-01"
    },
    "message": {
        "bot_id": "B0T123456",
        "type": "message",
        "text": "Text+here+for+notifications",
        "user": "ABCDE6789",
        "ts": "1628851405.000300",
        "blocks": [
            {
                "type": "input",
                "block_id": "bK6",
                "label": {
                    "type": "plain_text",
                    "text": "Select+Location",
                    "emoji": true
                },
                "optional": false,
                "dispatch_action": false,
                "element": {
                    "type": "external_select",
                    "action_id": "location_select-action",
                    "placeholder": {
                        "type": "plain_text",
                        "text": "Select+location",
                        "emoji": true
                    }
                }
            }
        ],
        "team": "ENT4567"
    }
}
Build something social for your team on Slack
πŸƒβ€β™€οΈ Customize our Running Buddies tutorial for your favorite activities