Docs / Integration API contract

Modals

A view is Slack's modal reduced to what this server can draw:

  • title, submit, close, callback_id and private_metadata;
  • input blocks, with label, hint and optional, each holding one of the elements below;
  • header, section, context and divider blocks, shown where they sit among the inputs: a header as a heading, a section (with its fields after it) as text, a context as small print, and a divider as a line.

The input elements — checked:

ElementHonouredAnswer in state.values
plain_text_inputmultiline, placeholder, initial_valuevalue
static_selectoptions or option_groups, placeholder, initial_optionselected_option
multi_static_selectAs above, with initial_options and max_selected_itemsselected_options
checkboxesoptions with description, initial_optionsselected_options
radio_buttonsoptions with description, initial_optionselected_option
users_selectplaceholder, initial_userselected_user
multi_users_selectplaceholder, initial_users, max_selected_itemsselected_users
conversations_selectplaceholder, initial_conversation, default_to_current_conversation, filter.includeselected_conversation
multi_conversations_selectAs above, with initial_conversations and max_selected_itemsselected_conversations
channels_selectplaceholder, initial_channelselected_channel
multi_channels_selectplaceholder, initial_channels, max_selected_itemsselected_channels
datepickerplaceholder, initial_dateselected_date, YYYY-MM-DD
timepickerinitial_timeselected_time, HH:mm
  • A select takes up to 100 options, and checkboxes and radio buttons up to 10, as on Slack. Option groups are run together into one list. A choice left with no usable options is dropped.
  • The people pickers offer everyone with an active account except bots. The conversation pickers offer what the person filling in the form can open, limited by filter.include (public, private, im, mpim). The channel pickers offer public channels. Archived conversations are never offered.
  • default_to_current_conversation starts a conversation picker on the conversation where the slash command was run or the button pressed.
  • A starting value the person cannot see is left out rather than sent unseen.
  • Not honoured: exclude_bot_users and exclude_external_shared_channels in a filter, min_length and max_length on text, timezone on a time picker, focus_on_load, dispatch_action and response_url_enabled.

An input of any other kind, such as datetimepicker, number_input, email_text_input, file_input or external_select, is dropped rather than drawn as a control that does nothing. At most 25 inputs are kept.

Submitting posts a form with a payload field holding Slack's view_submission: team, user, api_app_id, a fresh trigger_id, and view with id, callback_id, private_metadata, title and state.values. Each value names its element as type and holds its answer under the key in the table, as Slack sends it: a chosen option is {"text": {"type": "plain_text", "text": "…"}, "value": "…"}, with a description if it had one, and people and conversations are ids. An optional input left empty answers "" for text, null for one choice and [] for several.

Before anything reaches the app, the server refuses a submission that leaves a required input empty, or chooses something the input never offered: an option it did not list, more than max_selected_items, an account that is not active, a conversation the person cannot open or the filter leaves out, a channel that is not public, or a date or time that does not exist. So an app never has to defend against a form its own view forbids.

The app's answer:

  • anything that is not an error or one of the actions below closes the view, including an empty body, and shows the one under it if there is one;
  • {"response_action": "errors", "errors": {"<block_id>": "<message>"}} keeps it open with each message shown against its input;
  • {"response_action": "update", "view": {…}} changes the view, as views.update would;
  • {"response_action": "push", "view": {…}} stacks a view on it, as views.push would;
  • {"response_action": "clear"} closes every view in the stack;
  • an answer that starts like JSON but cannot be read keeps it open, and the person is told the app's answer could not be read, as does an update or push whose view cannot be shown or would be a fourth;
  • an error status, or no answer within four seconds, keeps it open and says so.

Only the view on top can be submitted. Its view in the payload also carries hash, external_id, root_view_id and previous_view_id (null for the first). The close button of a stacked view goes back to the one under it; the dialog's own close and Escape close them all. Closing tells the app nothing: notify_on_close and view_closed are not supported. A view is open for thirty minutes, and is closed without reaching the app if its conversation or app goes away in that time.

This page is made from docs/INTEGRATIONS.md.