This is reference content about building functions and workflows. Learn more if you're not yet familiar with this new Slack platform paradigm.

open_form

Open an interactive form

Facts

Schema ID

Schema.slack.functions.OpenForm

Schema reference

slack#/functions/open_form

Required scopes

No additional scopes are required.

Input parameters

Required parameters
Title of the form shown to the user (24 characters / 8 Japanese characters max)
  • How am I driving?
  • TPS Report Submission
  • Channel hero nomination
A collection of input fields to be shown on the form. See Using forms for schema.
Context about the interactive event that led to opening of the form. See form interactivity for more.
Optional parameters
Description of the form shown to the user
  • Request access to the underground lair on weekends
  • Submit your ideas to the think tank
  • Choose your next adventure
Label of the submit button that the user will click to submit the form
  • Submit complaint
  • Save call log
  • Open mailbox

Output parameters

Required parameters
Values of the input fields filled by the user. See Using forms for details.
Context about the form submit action interactive event

Usage guide

Forms are a straight-forward way to collect user input and pass it onto to other parts of your workflow. Their interactivity is one way - users interact with a static form. You cannot update the form itself based on user input.

Refer to Creating a form for guidance.

Form element schema

Form elements have several properties you can customize depending on the element type.

Links using Markdown are supported in the top-level description, but not in individual form element descriptions. See the Announcement Bot tutorial for an example.

Property Type Description
name String The internal name of the element
title String Title of the form shown to the user. Maximum length is 25 characters
type Schema.slack.types.* The type of form element to display
description String (optional) Description of the form shown to the user
default Same type as type (optional) Default value for this field

Form element type parameters

The following parameters are available for each type when defining your form. For each parameter listed, type is required.

Note the distinction that some element types are prefixed with Schema.types, while some are prefixed with Schema.slack.types.

Type Parameters Notes
Schema.types.string title, description, default, minLength, maxLength, format, enum, choices, long, type If the long parameter is provided and set to true, it will render as a multi-line text box. Otherwise, it renders as a single-line text input field. In addition, basic input validation can be done by setting format to either email or url
Schema.types.boolean title, description, default, type A boolean rendered as a radio button in the form
Schema.types.integer title, description, default, enum, choices, type, minimum, maximum A whole number, such as -1, 0, or 31415926535
Schema.types.number title, description, default, enum, choices, type, minimum, maximum A number that allows decimal points, such as 13557523.0005
Schema.types.array title, description, default, type, items, maxItems, display_type The required items parameter is an object itself, which must have a type sub-property defined. It can accept multiple different kinds of sub-properties based on the type chosen. Can be Schema.types.string, Schema.slack.types.channel_id, Schema.slack.types.user_id.

The display_type parameter can be used if the items object has the type parameter set to Schema.types.string and contains an enum parameter. The display_type parameter can then be set to multi_static_select (default) or checkboxes.
Schema.slack.types.date title, description, default, enum, choices, type A string containing a date, displayed in YYYY-MM-DD format
Schema.slack.types.timestamp title, description, default, enum, choices, type A Unix timestamp in seconds, rendered as a date picker
Schema.slack.types.user_id title, description, default, enum, choices, type A user picker
Schema.slack.types.channel_id title, description, default, enum, choices, type A channel picker
Schema.slack.types.rich_text title, description, default, type A way to nicely format messages in your app. Note that this type cannot be converted to other message types, such as a string
Schema.slack.types.file_id title, description, type, allowed_filetypes_group, allowed_filetypes Needs the files:read scope.

Example workflow step:

const openFormStep = SayHelloWorkflow.addStep(
  Schema.slack.functions.OpenForm,
  {
    title: "Send a greeting",
    interactivity: SayHelloWorkflow.inputs.interactivity,
    submit_label: "Send",
    fields: {
      elements: [{
        name: "recipient",
        title: "Recipient",
        type: Schema.slack.types.user_id,
      }, {
        name: "channel",
        title: "Channel to send message to",
        type: Schema.slack.types.channel_id,
        default: SayHelloWorkflow.inputs.channel,
      }, {
        name: "message",
        title: "Message to recipient",
        type: Schema.types.string,
        long: true,
      }],
      required: ["recipient", "channel", "message"],
    },
  },
);

Additional requirements

When creating a workflow that will have a step to open a form, your workflow must have the call to OpenForm be its first step or ensure the preceding step is interactive. An interactive step will generate a fresh pointer to use for opening the form.

Here's an example of a basic workflow definition using interactivity:

import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";

export const SayHelloWorkflow = DefineWorkflow({
  callback_id: "say_hello_workflow",
  title: "Say Hello to another user",
  input_parameters: {
    properties: {
      interactivity: {
        type: Schema.slack.types.interactivity,
      },
    },
    required: ["interactivity"],
  },
});