Legacy: A field guide to interactive messages

The interactive message framework layers atop typical Slack messages and makes heavy use of message formatting and attachments.

The fields and values and patterns used in the call and response sequence of an evolving workflow are particularly specialized when working with message menus and message buttons.

This guide will help you sort through the various fields encountered and utilized with interactive messages.

Some of these attributes must be adapted to POST parameters when using chat.postMessage.

Top-level message fields

Messages act as delivery vehicle for all interactive message experiences. Use them not only when initiating messages, but also when updating or creating evolving workflows.

See the formatting guide for text markup tips.

Attachment fields

Consult the guide to attaching content to messages for more flavor on working with attachments. Attachments house message buttons.

These fields should be presented as a hash within an array presented in the message's attachments field.

Message action fields

The actions you provide will be rendered as message buttons or menus to users.

Be sure and consult our best practices and storyboard your button interactions.

These fields should be provided as a JSON hash within an array as part of an attachment definition defined in the attachments field of a message (see above).

Confirmation fields

Protect users from destructive actions or particularly distinguished decisions by asking them to confirm their button click one more time. Use confirmation dialogs with care.

These fields should be presented as a JSON hash buried deep within the confirm field of an action within the actions array that's also part of an attachment that's inside the attachments array field of a message.

Example:

"confirm": {
    "title": "Are you sure?",
    "text": "Wouldn't you prefer a good game of chess?",
    "ok_text": "Yes",
    "dismiss_text": "No"
}

Option fields to place within message menu actions

A collection of option fields. Used in static and external message menu data types.

The value is especially important when used in selected_options and must match one of the previously provided options.

Example in context:

{
    "options": [
        {
            "text": "Barren Realms Elite",
            "value": "barren_realms_elite"
        },
        {
            "text": "Legend of the Red Dragon",
            "value": "legend_of_the_red_dragon"
        },
        {
            "text": "Solar Realms Elite",
            "value": "solar_realms_elite"
        },
        {
            "text": "Tradewars 2002",
            "value": "tradewars_2002"
        }
    ]
}

Option groups to place within message menu actions

Options groups are a set of 100 options divided into groups. They can be used with static or external message menu data types.

Example in context:

{
    "option_groups": [
        {
            "text": "Doggone bot antics",
            "options": [
                    {
                        "text": "Unexpected sentience",
                        "value": "AI-2323"
                    },
                    {
                        "text": "Bot biased toward other bots",
                        "value": "SUPPORT-42"
                    },
                    {
                        "text": "Bot broke my toaster",
                        "value": "IOT-75"
                    }
            ]
        },
        {
            "text": "Human error",
            "options": [
                {
                    "text": "Not Penny's boat",
                    "value": "LOST-7172"
                },
                {
                    "text": "We built our own CMS",
                    "value": "OOPS-1"
                }
            ]
        }
    ]
}

Action URL invocation payload

The key to interactive messages is the noble message and its attachments, but the fields delivered to your action URL whenever a button is pressed or a menu option is selected yields all the context your app needs to determine the next step.

Example:

{
        "type": "interactive_message",
        "actions": [
            {
                "name": "channels_list",
                "selected_options": [
                    {
                    "value": "C012AB3CD"
                    }
                ]
            }
        ],
        "callback_id": "select_simple_1234",
        "team": {
            "id": "T012AB0A1",
            "domain": "pocket-calculator"
        },
        "channel": {
            "id": "C012AB3CD",
            "name": "general"
        },
        "user": {
            "id": "U012A1BCD",
            "name": "musik"
        },
        "action_ts": "1481579588.685999",
        "message_ts": "1481579582.000003",
        "attachment_id": "1",
        "token": "iUeRJkkRC9RMMvSRTd8gdq2m",
        "original_message": {
                "text": "It's time to nominate the channel of the week",
                "bot_id": "B08BCU62D",
                "attachments": [
                    {
                       "callback_id": "select_simple_1234",
                       "fallback": "Upgrade your Slack client to use messages like these.",
                       "id": 1,
                       "color": "3AA3E3",
                       "actions": [
                           {
                               "id": "1",
                               "name": "channels_list",
                               "text": "Which channel changed your life this week?",
                               "type": "select",
                               "data_source": "channels"
                           }
                        ]
                    }
                ],
                "type": "message",
                "subtype": "bot_message",
                "ts": "1481579582.000003"
        },
        "response_url": "https://hooks.slack.com/actions/T012AB0A1/123456789/JpmK0yzoZDeRiqfeduTBYXWQ"
}

Options Load URL payload

When using external menus, Slack will send your Options Load URL a request to retrieve dynamic options for the interfacing user.

The invocation's payload includes important context on the user, workspace, and message you can use to determine which options to provide in response.

Its structure is similar to an Action URL invocation.

Example:

{
    "name": "bugs_list",
    "value": "bot",
    "callback_id": "select_remote_1234",
    "type": "interactive_message",
    "team": {
        "id": "T012AB0A1",
        "domain": "pocket-calculator"
    },
    "channel": {
        "id": "C012AB3CD",
        "name": "general"
    },
    "user": {
        "id": "U012A1BCJ",
        "name": "bugcatcher"
    },
    "action_ts": "1481670445.010908",
    "message_ts": "1481670439.000007",
    "attachment_id": "1",
    "token": "verification_token_string"
}

Good luck out in "the field."