Skip to content
Instant

Developers

Forms and shortcuts

A bot can ask for details in a proper form, and offer shortcuts in the / menu and on every message. Both use Slack’s views and payloads.

Open a Form

Every click, slash command and shortcut comes with a trigger_id. Within 10 seconds, pass it to views.open with a modal view, and the form opens at once over the app for that person, with the bot’s face and name above the fields.

app.command('/ticket', async ({ ack, body, client }) => {
  await ack();
  await client.views.open({
    trigger_id: body.trigger_id,
    view: {
      type: 'modal',
      callback_id: 'new_ticket',
      private_metadata: body.channel_id,
      title: { type: 'plain_text', text: 'New Ticket' },
      submit: { type: 'plain_text', text: 'File It' },
      blocks: [
        { type: 'input', block_id: 'title', label: { type: 'plain_text', text: 'Title' },
          element: { type: 'plain_text_input', action_id: 'value', placeholder: { type: 'plain_text', text: 'Export stalls at 99%' } } },
        { type: 'input', block_id: 'priority', label: { type: 'plain_text', text: 'Priority' },
          element: { type: 'static_select', action_id: 'value', options: ['P1', 'P2', 'P3'].map((p) => ({ text: { type: 'plain_text', text: p }, value: p })) } },
        { type: 'input', block_id: 'owner', optional: true, label: { type: 'plain_text', text: 'Owner' },
          element: { type: 'users_select', action_id: 'value' } },
      ],
    },
  });
});

What a Form Can Hold

BlockShows as
header, section, context, dividerText, like a message, between the fields
plain_text_inputA text field, one line or multiline. email_text_input, url_text_input and number_input show as text fields too.
static_select, multi_static_selectA menu, or a list to pick several from
users_selectA people picker
conversations_select, channels_selectA channel picker, showing only channels the person can see
checkboxes, radio_buttonsCheckboxes and radio buttons
datepickerA date field

Labels, hints, placeholders, initial values and optional all work. Any other element in an input is refused with invalid_arguments; other kinds of block are skipped.

When It’s Submitted

Instant checks required fields and offered options first, in the app and on the server, so the bot never sees a half-filled form. Then it sends Slack’s view_submission with view.state.values, callback_id, private_metadata, hash and a fresh trigger_id.

app.view('new_ticket', async ({ ack, view, body, client }) => {
  const v = view.state.values;
  const title = v.title.value.value.trim();
  if (title.length < 5) {
    await ack({ response_action: 'errors', errors: { title: 'Say a little more.' } });
    return;
  }
  await ack();
  await client.chat.postMessage({
    channel: view.private_metadata,
    text: `New ${v.priority.value.selected_option.value} ticket from <@${body.user.id}>: ${title}`,
  });
});

Answer within 3 seconds:

  • Nothing (an empty ack()) closes the form.
  • response_action: "errors" shows each message under its field and keeps the form open.
  • "update" replaces the form with a new view; "push" stacks another on top (three deep at most); "clear" closes them all.

Later, views.update changes an open form by view_id or external_id, with hash to refuse a stale write (hash_conflict), and views.push stacks one from a new trigger_id. When the person closes it, a view with notify_on_close sends the bot view_closed.

Shortcuts

Shortcuts let people start something with your bot without remembering a command. Add them on the bot’s page under Shortcuts: a name, a one-line description and the callback_id your code listens for. They need the commands scope and an Interactivity URL or Socket Mode; a bot can have 10.

  • Global shortcuts show in everyone’s / menu with the bot’s face, typed as their name: New Ticket is /new-ticket. They send Slack’s shortcut payload with callback_id, user, team and a trigger_id, and no channel, as on Slack.
  • On Messages shortcuts show in each message’s Shortcuts menu, and in the sheet when you hold a message on a phone. They send message_action with the channel, the message, a trigger_id and a response_url for 30 minutes.
app.shortcut('make_ticket', async ({ ack, shortcut, client }) => {
  await ack();
  await client.views.open({
    trigger_id: shortcut.trigger_id,
    view: ticketForm({ title: shortcut.message.text, channel: shortcut.channel.id }),
  });
});

Build Your First Bot

Make a bot in Settings › Bots & Apps and post your first message in a minute.

Join NowSee Pricing