Snapkit

This section explores how to create a custom user interface using snap-kit and DevRev.

Understanding the structure

The snap-kit JSON has a top-level structure with object, body, type, and snap_kit_body fields. The snap_kit_body field contains information regarding snap-kit’s structure.

For example:

1
{
2
  "object": "<source_id>",
3
  "body": "Giphy",
4
  "type": "timeline_comment",
5
  "snap_kit_body": {}
6
}

Snap-kit body

The snap_kit_body field has the following properties:

• snap_in_id: A unique identifier for the snap-kit.
• snap_in_action_name: The name of the action this snap-kit represents.
• body: An object that holds the actual snap-kit content in the form of snaps.

For example:

1
"snap_kit_body": {
2
  "snap_in_id": "<snap_in_id>",
3
  "snap_in_action_name": "giphy",
4
  "body": { "snaps": [] }
5
}

Body

The body field contains an array of snaps. Each snap can have a type, and depending on the type, it has different properties.

Snaps

The following snap types are supported:

Base types

• Snap
• Action
• Focusable
• Placeholder
• Disabled
• Hideable
• Layout

User interface elements

• Button
• Divider
• Image
• Plain Text
• Rich Text

Form elements

• Checkboxes
• Input
  • Plain Text Input
  • Number Input
  • Email Input
  • Rich Text Input
• List Input
  • String List Input
  • Number List Input
  • Email List Input
• Static Select
• Multi Static Select
• Radio Buttons
• Toggle Button
• Upload Input

Layout elements

• Actions
• Card
• Content
• Form
• Layout
• Input Layout

Data pickers

• Part Picker
• Tag Picker
• User Picker

Action payloads

Snap-kit generates payloads when a user interacts with an actionable snap. The payload is sent to the backend and can be used to perform actions. The following snaps generate payloads:

• Button
• Checkboxes
• Input and all its types (Plain Text Input, Number Input, Email Input, Rich Text Input)
• List Input and all its types (String List Input, Number List Input, Email List Input)
• Static Select
• Multi Static Select
• Radio Buttons
• Toggle Button
• Upload Input
• Form
• Part Picker
• Tag Picker
• User Picker

Base Payload

All actionable snaps share the same base payload structure. The base payload has the following structure:

1
{
2
  "type": "<type of Snap that generated the payload>",
3
  "action_id": "<the action identifier of the Snap that generated the payload>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>"
6
}

Base Types

Many elements share the same base properties. The base types these elements inherit from are described below.

Snap

A snap is the base type that all other snaps inherit from.

Properties

• type (required): Type of snap
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Action

Base interface for action components.

Action types

There are two types of action:

• Remote action: It triggers a backend API and is handled by the backend.
• Client action: It triggers a client-side action and is handled by the client.

Properties

• action_id (required): An identifier for the action. It should be unique in the snap.
• action_type (optional): Indicates whether the backend or client handles the action. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited properties

Inherited from Snap:

• type (required): Type of snap.
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Focusable

Base interface for focusable components.

Properties

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Placeholder

Base interface for components that can have a placeholder.

Properties

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Disabled

Base interface for components that can be disabled.

Properties

• disabled (optional): Indicates whether the element is disabled.

Hideable

Base interface for components that can be hidden.

Properties

• hidden (optional): Indicates whether the element is hidden.

Layout

Controls how the layout is displayed. Similar to flexbox.

Properties

• direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
• alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
• justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

User interface elements

Button

A button that can be clicked to trigger an action. Works with Actions and Form blocks.

Properties

• text (required): The text to be displayed on the button.
• style (optional): The style of the button. Defaults to "default". Possible values: "default", "primary", "destructive".
• value (required): The value associated with the button. It’s sent along with the interaction payload.
• href (optional): If the button is a link, this is the URL it links to.
• disabled (optional): Disables the input and prevents changes to the value.
• disabled_text (optional): The text that’s shown on hover if the component is disabled.

Inherited properties

Inherited from Snap:

• type (required): The type of the button component, should be set to "button".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action and is unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Example

Button variants are displayed in a row using the Card snap.

1
{
2
  "elements": [
3
    {
4
      "direction": "row",
5
      "elements": [
6
        {
7
          "action_id": "PRIMARY",
8
          "action_type": "remote",
9
          "style": "primary",
10
          "text": {
11
            "text": "PRIMARY",
12
            "type": "plain_text"
13
          },
14
          "type": "button",
15
          "value": "PRIMARY"
16
        },
17
        {
18
          "action_id": "SECONDARY",
19
          "action_type": "remote",
20
          "style": "secondary",
21
          "text": {
22
            "text": "SECONDARY",
23
            "type": "plain_text"
24
          },
25
          "type": "button",
26
          "value": "SECONDARY"
27
        },
28
        {
29
          "action_id": "DESTRUCTIVE",
30
          "action_type": "remote",
31
          "style": "destructive",
32
          "text": {
33
            "text": "DESTRUCTIVE",
34
            "type": "plain_text"
35
          },
36
          "type": "button",
37
          "value": "DESTRUCTIVE"
38
        },
39
        {
40
          "action_id": "TERTIARY",
41
          "action_type": "remote",
42
          "style": "tertiary",
43
          "text": {
44
            "text": "TERTIARY",
45
            "type": "plain_text"
46
          },
47
          "type": "button",
48
          "value": "TERTIARY"
49
        },
50
        {
51
          "action_id": "PRIMARY",
52
          "action_type": "remote",
53
          "disabled": true,
54
          "style": "primary",
55
          "text": {
56
            "text": "DISABLED",
57
            "type": "plain_text"
58
          },
59
          "type": "button",
60
          "value": "PRIMARY"
61
        }
62
      ],
63
      "type": "actions"
64
    }
65
  ],
66
  "type": "card"
67
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "button".

1
{
2
  "type": "button",
3
  "action_id": "<the action identifier of the button>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<the value associated with the button>"
7
}

Example payload

1
{
2
  "action_id": "PRIMARY",
3
  "action_type": "remote",
4
  "type": "button",
5
  "value": "PRIMARY",
6
  "timestamp": "2023-07-12T08:12:10.006Z"
7
}

Divider

A divider component is used to separate blocks.

Properties

The divider component does not have any properties of its own.

Inherited properties

Inherited from Snap:

• type (required): The type of the divider component, should be set to "divider".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

Divider is used in a form to separate a name input and a multi-select input.

1
{
2
  "elements": [
3
    {
4
      "action_id": "example_form",
5
      "elements": [
6
        {
7
          "element": {
8
            "action_id": "example_name",
9
            "placeholder": {
10
              "text": "Enter your name",
11
              "type": "plain_text"
12
            },
13
            "type": "plain_text_input"
14
          },
15
          "label": {
16
            "text": "Name",
17
            "type": "plain_text"
18
          },
19
          "type": "input_layout"
20
        },
21
        {
22
          "type": "divider"
23
        },
24
        {
25
          "element": {
26
            "action_id": "example_preferences",
27
            "options": [
28
              {
29
                "text": {
30
                  "text": "Email",
31
                  "type": "plain_text"
32
                },
33
                "value": "email"
34
              },
35
              {
36
                "text": {
37
                  "text": "Slack",
38
                  "type": "plain_text"
39
                },
40
                "value": "slack"
41
              },
42
              {
43
                "text": {
44
                  "text": "Other",
45
                  "type": "plain_text"
46
                },
47
                "value": "other"
48
              }
49
            ],
50
            "type": "multi_static_select"
51
          },
52
          "label": {
53
            "text": "Select your preferred ways of communication",
54
            "type": "plain_text"
55
          },
56
          "type": "input_layout"
57
        },
58
        {
59
          "element": {
60
            "action_id": "example_other",
61
            "type": "plain_text_input"
62
          },
63
          "label": {
64
            "text": "Additional Notes",
65
            "type": "plain_text"
66
          },
67
          "optional": true,
68
          "type": "input_layout"
69
        }
70
      ],
71
      "submit_action": {
72
        "action_id": "example_button",
73
        "style": "primary",
74
        "text": {
75
          "text": "Submit",
76
          "type": "plain_text"
77
        },
78
        "type": "button",
79
        "value": "SUBMIT"
80
      },
81
      "type": "form"
82
    }
83
  ],
84
  "type": "card"
85
}

Image

An image block that displays an image. Works with Content blocks.

Properties

• image_url (required): The URL of the image.
• alt_text (required): The alt text to be displayed when the image can’t be displayed. This shouldn’t contain any markup.
• fill_container (optional): Whether the image should stretch to fill the container while maintaining its aspect ratio.

Inherited properties

Inherited from Snap:

• type (required): The type of the image component, should be set to "image".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

Image used in a card, with default display mode (fill_container not set).

1
{
2
  "elements": [
3
    {
4
      "alignment": "center",
5
      "elements": [
6
        {
7
          "text": "Default image display mode: Creating a group in DevRev",
8
          "type": "plain_text"
9
        },
10
        {
11
          "alt_text": "Group creation",
12
          "image_url": "https://docs.devrev.ai/_next/image?url=%2Fimg%2Fgroups.gif&w=750&q=75",
13
          "type": "image"
14
        }
15
      ],
16
      "type": "content"
17
    }
18
  ],
19
  "type": "card"
20
}

Image used in a card, with fill_container set.

1
{
2
  "elements": [
3
    {
4
      "alignment": "center",
5
      "elements": [
6
        {
7
          "text": "Fill container image display mode: Creating a group in DevRev",
8
          "type": "plain_text"
9
        },
10
        {
11
          "alt_text": "Group creation",
12
          "image_url": "https://docs.devrev.ai/_next/image?url=%2Fimg%2Fgroups.gif&w=750&q=75",
13
          "type": "image"
14
        }
15
      ],
16
      "type": "content"
17
    }
18
  ],
19
  "type": "card"
20
}

Plain text

A plain text element is used to define unformatted text.

Properties

• text (required): The plain text content.

Inherited properties

Inherited from Snap:

• type (required): The type of the element, should be set to "plain_text".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

1
{
2
  "elements": [
3
    {
4
      "text": "Hello this is an example of a plain text element",
5
      "type": "plain_text"
6
    }
7
  ]
8
}

Rich text

A rich text element is used to define formatted text.

Properties

• text (required): The rich text content.

Inherited properties

Inherited from Snap:

• type (required): The type of the element, should be set to "rich_text".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

1
{
2
  "text": "# Welcome to DevRev! \n[DevRev](https://devrev.ai)",
3
  "type": "rich_text"
4
}

Form elements

Plain text option

Plain text options are a commonly shared component of different form elements. It’s used to define an option in a form element.

• text (required): A Plain Text element representing the option.
• value (required): A value assigned to the option.
• description (optional): An optional Plain Text element describing the option.

Checkboxes

A component that provides a group of checkboxes that allow a user to choose multiple items from a list of options. Works with Input Layout and Actions blocks.

Properties

• options (required): A list of options that appears in a stack of checkboxes, of type Plain Text Option.
• initial_options (optional): The initially selected options.

Inherited properties

Inherited from Snap:

• type (required): The type of the checkbox group component, should be set to "checkboxes".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

1
{
2
  "elements": [
3
    {
4
      "action_id": "checkboxes",
5
      "action_type": "remote",
6
      "options": [
7
        {
8
          "description": {
9
            "text": "Description for option 1",
10
            "type": "plain_text"
11
          },
12
          "text": {
13
            "text": "Option 1",
14
            "type": "plain_text"
15
          },
16
          "value": "option_1"
17
        },
18
        {
19
          "description": {
20
            "text": "Description for option 1",
21
            "type": "plain_text"
22
          },
23
          "text": {
24
            "text": "Option 2",
25
            "type": "plain_text"
26
          },
27
          "value": "option_2"
28
        }
29
      ],
30
      "type": "checkboxes"
31
    },
32
    {
33
      "action_id": "checkboxes",
34
      "action_type": "remote",
35
      "disabled": true,
36
      "options": [
37
        {
38
          "description": {
39
            "text": "Description for option 1",
40
            "type": "plain_text"
41
          },
42
          "text": {
43
            "text": "Disabled Option 1",
44
            "type": "plain_text"
45
          },
46
          "value": "option_1"
47
        },
48
        {
49
          "description": {
50
            "text": "Description for option 1",
51
            "type": "plain_text"
52
          },
53
          "text": {
54
            "text": "Disabled Option 2",
55
            "type": "plain_text"
56
          },
57
          "value": "option_2"
58
        }
59
      ],
60
      "type": "checkboxes"
61
    }
62
  ],
63
  "type": "actions"
64
}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "checkboxes".

1
{
2
  "type": "checkboxes",
3
  "action_id": "<the action identifier of the checkboxes>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<array of selected Plain Text Option objects>"]
7
}

Example payload

1
{
2
  "action_id": "checkboxes",
3
  "action_type": "remote",
4
  "type": "checkboxes",
5
  "value": [
6
    {
7
      "description": {
8
        "text": "Description for option 1",
9
        "type": "plain_text"
10
      },
11
      "text": { "text": "Option 2", "type": "plain_text" },
12
      "value": "option_2"
13
    }
14
  ],
15
  "timestamp": "2023-07-12T08:14:52.370Z"
16
}

Input

There are 4 supported input types:

• Plain Text Input
• Number Input
• Email Input
• Rich Text Input

Properties

The input component does not have any properties of its own. See specific variants below for their properties.

Inherited properties

Inherited from Snap:

• type (required): Type of the input component. Should be set according to the input type, see below.
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Plain text input

A plain-text input, similar to the HTML <input> tag, creates a field where a user can enter freeform data. It can appear as a single-line field. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "plain_text_input".

Additional properties

• initial_value (optional): The initial value in the input when it’s loaded.
• multiline (optional): Indicates whether the input should allow multiple lines of text. Defaults to false.
• min_length (optional): The minimum text length, can’t be greater than max_length.
• max_length (optional): The maximum text length, can’t be less than min_length.
• resize (optional): Indicates whether the input should be resizable. Defaults to false.

Example

1
{
2
  "element": {
3
    "action_id": "name",
4
    "min_length": 10,
5
    "placeholder": {
6
      "text": "Enter your name",
7
      "type": "plain_text"
8
    },
9
    "type": "plain_text_input"
10
  },
11
  "hint": {
12
    "text": "Please enter your name",
13
    "type": "plain_text"
14
  },
15
  "label": {
16
    "text": "User Name",
17
    "type": "plain_text"
18
  },
19
  "optional": true,
20
  "type": "input_layout"
21
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "plain_text_input".

1
{
2
  "type": "plain_text_input",
3
  "action_id": "<the action identifier of the plain text input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<the value of the input>"
7
}

Example payload

1
{
2
  "type": "plain_text_input",
3
  "action_id": "name",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-12T08:17:43.887Z",
6
  "value": "Chuck Norris"
7
}

Number input

A number input, similar to the HTML <input> tag, creates a field where a user can enter numbers. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "number_input".

Additional properties

• initial_value (optional): The initial value in the input when it’s loaded.
• min_value (optional): The minimum value, can’t be greater than max_value.
• max_value (optional): The maximum value, can’t be less than min_value.

Example

1
{
2
  "element": {
3
    "action_id": "age",
4
    "max_value": 120,
5
    "min_value": 10,
6
    "type": "number_input"
7
  },
8
  "label": {
9
    "text": "Age",
10
    "type": "plain_text"
11
  },
12
  "type": "input_layout"
13
}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "number_input".

1
{
2
  "type": "number_input",
3
  "action_id": "<the action identifier of the number input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<the value of the input>"
7
}

Example payload

1
{
2
  "type": "number_input",
3
  "action_id": "age",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-12T08:17:43.887Z",
6
  "value": "83"
7
}

Email input

An email input, similar to the HTML <input> tag, creates a field where a user can enter email. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "email_text_input".

Additional properties

• initial_value (optional): The initial value in the input when it’s loaded.

Example

1
{
2
  "element": {
3
    "action_id": "email",
4
    "placeholder": {
5
      "text": "example@devrev.ai",
6
      "type": "plain_text"
7
    },
8
    "type": "email_text_input"
9
  },
10
  "hint": {
11
    "text": "Please enter your email",
12
    "type": "plain_text"
13
  },
14
  "label": {
15
    "text": "Email",
16
    "type": "plain_text"
17
  },
18
  "type": "input_layout"
19
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "email_text_input".

1
{
2
  "type": "email_text_input",
3
  "action_id": "<the action identifier of the email text input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<the value of the input>"
7
}

Example payload

1
{
2
  "type": "email_text_input",
3
  "action_id": "email",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-12T08:17:43.887Z",
6
  "value": "chuck@norris.com"
7
}

Rich text input

A rich text input shows a rich text editor where the user can enter formatted text (Markdown). Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "rich_text_input".

Additional properties

• initial_value (optional): The initial value in the input when it’s loaded.

Example

The following video shows the rich text input in action.

1
{
2
  "element": {
3
    "action_id": "notes",
4
    "placeholder": {
5
      "text": "Your notes go here",
6
      "type": "plain_text"
7
    },
8
    "type": "rich_text_input"
9
  },
10
  "hint": {
11
    "text": "Please enter your notes",
12
    "type": "plain_text"
13
  },
14
  "label": {
15
    "text": "Notes",
16
    "type": "plain_text"
17
  },
18
  "optional": true,
19
  "type": "input_layout"
20
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "rich_text_input".

1
{
2
  "type": "rich_text_input",
3
  "action_id": "<the action identifier of the rich text input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<the value (raw Markdown) of the input>"
7
}

Example payload

1
{
2
  "type": "rich_text_input",
3
  "action_id": "notes",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-19T10:54:20.331Z",
6
  "value": "**Title**
7
8
*Italic*
9
10
~~Strikethrough~~
11
12
`A piece of code`
13
14
> A quote
15
16
- Unordered 1
17
- Unordered 2
18
19
1. Ordered 1
20
2. Ordered 2"
21
}

List input

There are 3 supported list input types:

• String List Input
• Number List Input
• Email List Input

Properties

The list input component does not have any properties of its own. See specific variants below for their properties.

Inherited properties

Inherited from Snap:

• type (required): Type of the list input component. Should be set according to the list input type, see below.
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Placeholder:

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

String list input

A string list input allows users to enter a list of text items. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "string_list".

Additional Properties

• min_items (optional): The minimum number of items that can be added. Defaults to 1.
• max_items (optional): The maximum number of items that can be added.
• multiline (optional): Indicates whether the input should allow multiple lines of text. Defaults to false.
• min_item_length (optional): The minimum text length of the inputs, can’t be greater than max_item_length.
• max_item_length (optional): The maximum text length of the inputs, can’t be less than min_item_length.
• initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.

Example

Standard string list input with a minimum of 1 item, maximum of 3 items, minimum item length set to 3 and maximum item length set to 15.

1
{
2
  "element": {
3
    "action_id": "keywords",
4
    "max_items": 3,
5
    "min_items": 1,
6
    "max_item_length": 15,
7
    "min_item_length": 3,
8
    "placeholder": {
9
      "text": "Add keyword here",
10
      "type": "plain_text"
11
    },
12
    "type": "string_list"
13
  },
14
  "hint": {
15
    "text": "When a customer includes these keywords in a Slack message, they are prompted to send the message to your DevRev inbox.",
16
    "type": "plain_text"
17
  },
18
  "label": {
19
    "text": "List of strings",
20
    "type": "plain_text"
21
  },
22
  "type": "input_layout"
23
}

Multiline string list input with a minimum of 1 item and a maximum of 2 items.

1
{
2
  "element": {
3
    "action_id": "multiline",
4
    "max_items": 2,
5
    "min_items": 1,
6
    "multiline": true,
7
    "placeholder": {
8
      "text": "Add a keyword here",
9
      "type": "plain_text"
10
    },
11
    "type": "string_list"
12
  },
13
  "hint": {
14
    "text": "When a customer includes these multiline keywords in a Slack message, they are prompted to send the message to your DevRev inbox.",
15
    "type": "plain_text"
16
  },
17
  "label": {
18
    "text": "List of strings",
19
    "type": "plain_text"
20
  },
21
  "type": "input_layout"
22
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "string_list".

1
{
2
  "type": "string_list",
3
  "action_id": "<the action identifier of the string list input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<an array of strings as inputted by the user>"]
7
}

Example payload

Standard string list input.

1
{
2
  "type": "string_list",
3
  "action_id": "keywords",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-21T05:33:52.182Z",
6
  "value": ["hello", "this is", "a test"]
7
}

Multiline string list input.

1
{
2
  "type": "string_list",
3
  "action_id": "multiline",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-21T05:33:52.182Z",
6
  "value": ["Hello this
7
is a multiline string", "And here
8
is another
9
one"]
10
}

Number List Input

A list of numbers input allows users to enter a list of numeric items. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "number_list".

Additional Properties

• min_items (optional): The minimum number of items that can be added.
• max_items (optional): The maximum number of items that can be added.
• min_item_value (optional): The minimum value of the inputs, can’t be greater than max_item_value.
• max_item_value (optional): The maximum value of the inputs, can’t be less than min_item_value.
• initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.

Example

1
{
2
  "element": {
3
    "action_id": "numbers",
4
    "max_item_value": 90,
5
    "min_item_value": 0,
6
    "placeholder": {
7
      "text": "Add warning value here (min 0, max 90)",
8
      "type": "plain_text"
9
    },
10
    "type": "number_list"
11
  },
12
  "hint": {
13
    "text": "Add warning values for code coverage reports",
14
    "type": "plain_text"
15
  },
16
  "label": {
17
    "text": "List of numbers",
18
    "type": "plain_text"
19
  },
20
  "type": "input_layout"
21
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "number_list".

1
{
2
  "type": "number_list",
3
  "action_id": "<the action identifier of the number list input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<an array of numbers as strings as inputted by the user>"]
7
}

Example Payload

1
{
2
  "type": "number_list",
3
  "action_id": "numbers",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-21T05:33:52.182Z",
6
  "value": ["25", "42", "60"]
7
}

Email List Input

A list of email input allows users to enter a list of emails. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

• type (required): The type of the input component, should be set to "email_list".

Additional Properties

• min_items (optional): The minimum number of items that can be added.
• max_items (optional): The maximum number of items that can be added.
• initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.

Example

1
{
2
  "element": {
3
    "action_id": "emails",
4
    "placeholder": {
5
      "text": "Enter email here",
6
      "type": "plain_text"
7
    },
8
    "type": "email_list"
9
  },
10
  "hint": {
11
    "text": "When these emails are included in a Slack message, they automatically receive an email notification.",
12
    "type": "plain_text"
13
  },
14
  "label": {
15
    "text": "List of emails",
16
    "type": "plain_text"
17
  },
18
  "type": "input_layout"
19
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "email_list".

1
{
2
  "type": "email_list",
3
  "action_id": "<the action identifier of the email list input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<an array of emails as strings as inputted by the user>"]
7
}

Example Payload

1
{
2
  "type": "email_list",
3
  "action_id": "emails",
4
  "action_type": "remote",
5
  "timestamp": "2023-07-21T05:33:52.182Z",
6
  "value": ["hello@hello.com", "example@example.com", "bonjour@hello.com"]
7
}

Static Select

A select menu that allows a user to choose one item from a list of options. Works with Input Layout and Actions blocks.

Properties

• options (required): A list of options that appear in the menu, of type Plain Text Option.
• initial_selected_option (optional): The initial option that’s selected when the element is loaded. A single option that exactly matches one of the options within options.

Inherited properties

Inherited from Snap:

• type (required): Type of the static select component, should be set to "static_select".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

A static select snap with 4 options.

1
{
2
  "action_id": "static_select",
3
  "action_type": "remote",
4
  "initial_selected_option": {
5
    "text": {
6
      "text": "Forrest Gump",
7
      "type": "plain_text"
8
    },
9
    "value": "forrest-gump"
10
  },
11
  "options": [
12
    {
13
      "text": {
14
        "text": "Forrest Gump",
15
        "type": "plain_text"
16
      },
17
      "value": "forrest-gump"
18
    },
19
    {
20
      "text": {
21
        "text": "The Shawshank Redemption",
22
        "type": "plain_text"
23
      },
24
      "value": "the-shawshank-redemption"
25
    },
26
    {
27
      "text": {
28
        "text": "The Godfather",
29
        "type": "plain_text"
30
      },
31
      "value": "the-godfather"
32
    },
33
    {
34
      "text": {
35
        "text": "The Dark Knight",
36
        "type": "plain_text"
37
      },
38
      "value": "the-dark-knight"
39
    }
40
  ],
41
  "type": "static_select"
42
}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "static_select".

1
{
2
  "type": "static_select",
3
  "action_id": "<the action identifier of the static select>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<selected Plain Text Option object>"
7
}

Example Payload

1
{
2
  "action_id": "static_select",
3
  "action_type": "remote",
4
  "type": "static_select",
5
  "value": {
6
    "text": { "text": "The Godfather", "type": "plain_text" },
7
    "value": "the-godfather"
8
  },
9
  "timestamp": "2023-07-12T08:21:06.027Z"
10
}

Multi Static Select

A select menu that allows a user to choose multiple items from a list of options. Works with Input Layout and Actions blocks.

Properties

• options (required): A list of options that appear in the menu, of type Plain Text Option.
• initial_selected_options (optional): The initial options that are selected when the element is loaded. Each of them should exactly match one of the options within options.
• max_selected_items (optional): The maximum number of items that can be selected.

Inherited properties

Inherited from Snap:

• type (required): The type of the multi-static select component, should be set to "multi_static_select".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

A multi-static select snap with 4 options.

1
{
2
  "action_id": "multi_static_select",
3
  "action_type": "remote",
4
  "initial_selected_options": [
5
    {
6
      "text": {
7
        "text": "Forrest Gump",
8
        "type": "plain_text"
9
      },
10
      "value": "forrest-gump"
11
    }
12
  ],
13
  "options": [
14
    {
15
      "text": {
16
        "text": "Forrest Gump",
17
        "type": "plain_text"
18
      },
19
      "value": "forrest-gump"
20
    },
21
    {
22
      "text": {
23
        "text": "The Shawshank Redemption",
24
        "type": "plain_text"
25
      },
26
      "value": "the-shawshank-redemption"
27
    },
28
    {
29
      "text": {
30
        "text": "The Godfather",
31
        "type": "plain_text"
32
      },
33
      "value": "the-godfather"
34
    },
35
    {
36
      "text": {
37
        "text": "The Dark Knight",
38
        "type": "plain_text"
39
      },
40
      "value": "the-dark-knight"
41
    }
42
  ],
43
  "type": "multi_static_select"
44
}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "multi_static_select".

1
{
2
  "type": "multi_static_select",
3
  "action_id": "<the action identifier of the multi-static select>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<array of selected Plain Text Option objects>"]
7
}

Example Payload

1
{
2
  "action_id": "multi_static_select",
3
  "action_type": "remote",
4
  "type": "multi_static_select",
5
  "value": [
6
    {
7
      "text": { "text": "Forrest Gump", "type": "plain_text" },
8
      "value": "forrest-gump"
9
    },
10
    {
11
      "text": { "text": "The Dark Knight", "type": "plain_text" },
12
      "value": "the-dark-knight"
13
    }
14
  ],
15
  "timestamp": "2023-07-12T08:21:24.700Z"
16
}

Radio Buttons

List of radio inputs that allow a user to choose one item from a list of options. Works with input layout and actions blocks.

Properties

• options (required): A list of options that appear in a stack of radio inputs, of type plain text option.
• initial_selected_option (optional): The initial option that’s selected when the element is loaded. A single option that exactly matches one of the options within options.

Inherited properties

Inherited from Snap:

• type (required): Type of the radio button group component, should be set to "radio_buttons".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

A radio button snap with 3 options.

1
{
2
  "action_id": "in-app",
3
  "action_type": "remote",
4
  "options": [
5
    {
6
      "text": {
7
        "text": "Important updates only (Mentions & assignments)",
8
        "type": "plain_text"
9
      },
10
      "value": "imp"
11
    },
12
    {
13
      "text": {
14
        "text": "All new updates",
15
        "type": "plain_text"
16
      },
17
      "value": "all"
18
    },
19
    {
20
      "text": {
21
        "text": "Never",
22
        "type": "plain_text"
23
      },
24
      "value": "none"
25
    }
26
  ],
27
  "type": "radio_buttons"
28
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "radio_buttons".

1
{
2
  "type": "radio_buttons",
3
  "action_id": "<the action identifier of the radio buttons>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<selected Plain Text Option object>"
7
}

Example Payload

1
{
2
  "action_id": "in-app",
3
  "action_type": "remote",
4
  "type": "radio_buttons",
5
  "value": {
6
    "text": { "text": "All new updates", "type": "plain_text" },
7
    "value": "all"
8
  },
9
  "timestamp": "2023-07-12T08:21:46.621Z"
10
}

Toggle Button

Toggles allow users to quickly switch between two possible states. Works with Input Layout and Actions blocks.

Properties

• initial_value (optional): The initial value of the toggle (a boolean).
• description (optional): A Plain Text element that defines the description shown below the toggle.

Inherited properties

Inherited from Snap:

• type (required): The type of the toggle button component, should be set to "toggle".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

1
{
2
  "elements": [
3
    {
4
      "elements": [
5
        {
6
          "action_id": "toggle",
7
          "description": {
8
            "text": "This is a toggle",
9
            "type": "plain_text"
10
          },
11
          "type": "toggle"
12
        },
13
        {
14
          "action_id": "toggle_checked",
15
          "description": {
16
            "text": "This is a checked toggle",
17
            "type": "plain_text"
18
          },
19
          "initial_value": true,
20
          "type": "toggle"
21
        },
22
        {
23
          "action_id": "toggle_disabled",
24
          "description": {
25
            "text": "This is a disabled toggle",
26
            "type": "plain_text"
27
          },
28
          "disabled": true,
29
          "type": "toggle"
30
        }
31
      ],
32
      "type": "actions"
33
    }
34
  ],
35
  "type": "card"
36
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "toggle".

1
{
2
  "type": "toggle",
3
  "action_id": "<the action identifier of the toggle>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": "<boolean indicating the state of the toggle>"
7
}

Example Payload

1
{
2
  "action_id": "toggle",
3
  "action_type": "remote",
4
  "type": "toggle",
5
  "value": true,
6
  "timestamp": "2023-07-12T08:22:10.723Z"
7
}

Upload Input

A component that allows a user to upload a file. Works with Input Layout and Actions blocks.

Properties

• upload_button (required): A button that can be clicked to upload files.
• min_files (optional): The minimum number of files that can be uploaded.
• max_files (optional): The maximum number of files that can be uploaded.
• initial_artifacts_ids (optional): The initial artifacts that are selected when the element is loaded. A list of DONv2 IDs.

Inherited properties

Inherited from Snap:

• type (required): Type of the upload input component, should be set to "upload".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

• action_id (required): An identifier for the action. Should be unique in the snap.
• action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

• focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

• placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

• disabled (optional): Indicates whether the element is disabled.

Example

1
{
2
  "elements": [
3
    {
4
      "elements": [
5
        {
6
          "action_id": "upload",
7
          "action_type": "remote",
8
          "max_files": 5,
9
          "min_files": 1,
10
          "type": "upload",
11
          "upload_button": {
12
            "action_id": "upload_btn",
13
            "style": "primary",
14
            "text": {
15
              "text": "Upload",
16
              "type": "plain_text"
17
            },
18
            "type": "button",
19
            "value": "upload"
20
          }
21
        }
22
      ],
23
      "type": "actions"
24
    }
25
  ],
26
  "type": "card"
27
}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "upload".

1
{
2
  "type": "upload",
3
  "action_id": "<the action identifier of the upload input>",
4
  "action_type": "<the type of the action as defined in the Snap>",
5
  "timestamp": "<timestamp as a string in ISO 8601 format>",
6
  "value": ["<an array of artifact IDs as strings>"]
7
}

Example Payload

1
{
2
  "action_id": "upload",
3
  "action_type": "remote",
4
  "type": "upload",
5
  "value": [
6
    "don:core:dvrv-us-1:devo/H66a8LUt:artifact/5",
7
    "don:core:dvrv-us-1:devo/H66a8LUt:artifact/6"
8
  ],
9
  "timestamp": "2023-07-12T08:25:47.451Z"
10
}

Layout Elements

Actions

Used when you want the user to interact without filling out a form. Similar to the Form block but without a submit button. It contains an array of elements.

Properties

• elements (required): An array of elements. See the list of allowed elements below.
• disable_on_action (optional): A boolean indicating whether all elements in the actions block should be disabled when one of the elements is interacted with. When the action is completed, the elements are re-enabled. Defaults to false. A use case for enabling this is if you have multiple actions that shouldn’t be executed concurrently or are incompatible with each other. An example of this would be a snap-in for selecting a meal for a company event. When the user selects a meal, the other meal options should be disabled until the order is placed. After that, the Snap-kit can be updated with the information about the selection.

Inherited properties

Inherited from Snap:

• type (required): The type of the actions component, should be set to "actions".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Layout:

• direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
• alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
• justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

• Button
• Checkboxes
• Radio Buttons
• Actions
• Static Select
• Multi Static Select
• Divider
• Tag Picker
• User Picker
• Part Picker
• Toggle Button
• Upload Input

Example

1
{
2
  "elements": [
3
    {
4
      "action_id": "actions",
5
      "action_type": "remote",
6
      "options": [
7
        {
8
          "text": {
9
            "text": "Checkbox 1",
10
            "type": "plain_text"
11
          },
12
          "value": "checkbox_1"
13
        },
14
        {
15
          "text": {
16
            "text": "Checkbox 2",
17
            "type": "plain_text"
18
          },
19
          "value": "checkbox_2"
20
        }
21
      ],
22
      "type": "checkboxes"
23
    },
24
    {
25
      "action_id": "submit",
26
      "action_type": "remote",
27
      "style": "primary",
28
      "text": {
29
        "text": "Button",
30
        "type": "plain_text"
31
      },
32
      "type": "button",
33
      "value": "submit"
34
    }
35
  ],
36
  "type": "actions"
37
}

The following video shows the behavior of the Actions block with disable_on_action set to true.

1
{
2
  "elements": [
3
    {
4
      "elements": [
5
        {
6
          "text": "This is an example of an Actions Snap with disable_on_action set to true. When you click one of the buttons, the other buttons are disabled until the action finishes.",
7
          "type": "plain_text"
8
        }
9
      ],
10
      "type": "content"
11
    },
12
    {
13
      "direction": "row",
14
      "disable_on_action": true,
15
      "elements": [
16
        {
17
          "action_id": "button_1",
18
          "action_type": "remote",
19
          "style": "primary",
20
          "text": {
21
            "text": "Button 1",
22
            "type": "plain_text"
23
          },
24
          "type": "button",
25
          "value": "button_1"
26
        },
27
        {
28
          "action_id": "button_2",
29
          "action_type": "remote",
30
          "style": "secondary",
31
          "text": {
32
            "text": "Button 2",
33
            "type": "plain_text"
34
          },
35
          "type": "button",
36
          "value": "button_2"
37
        },
38
        {
39
          "action_id": "button_3",
40
          "action_type": "remote",
41
          "style": "destructive",
42
          "text": {
43
            "text": "Button 3",
44
            "type": "plain_text"
45
          },
46
          "type": "button",
47
          "value": "button_3"
48
        }
49
      ],
50
      "type": "actions"
51
    }
52
  ],
53
  "type": "card"
54
}

Card

A card is a container for various types of content. It contains an array of elements.

Properties

• elements (required): An array of elements. See the list of allowed elements below.
• title (optional): The title of the card.
• is_collapsible (optional): Whether the card is collapsible or not. Defaults to false.
• default_collapsed (optional): Whether the card is collapsed by default or not. Defaults to false.

Inherited properties

Inherited from Snap:

• type (required): The type of the card component, should be set to "card".
• block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Layout:

• direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
• alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
• justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

• Actions
• Content
• Form
• Divider

Example

Default and collapsible card example.

1
[
2
  {
3
    "elements": [
4
      {
5
        "elements": [
6
          {
7
            "text": "Hello this is an example of a card that can have different types of elements inside it",
8
            "type": "plain_text"
9
          }
10
        ],
11
        "type": "content"
12
      }
13
    ],
14
    "type": "card"
15
  },
16
  {
17
    "default_collapsed": true,
18
    "elements": [
19
      {
20
        "elements": [
21
          {
22
            "text": "Hello this is an example of a collapsible card",
23
            "type": "plain_text"
24
          }
25
        ],
26
        "type": "content"
27
      }
28
    ],
29
    "is_collapsible": true,
30
    "title": {
31
      "text": "Collapsible Card Example",
32
      "type": "plain_text"
33
    },
34
    "type": "card"
35
  }
36
]