Snap-kit

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:

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 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 will be generated.

Action

Base interface for action components.

Action Types

There are two types of action:

Remote action: It will trigger a backend API and will be handled by the backend.
Client action: It will trigger a client-side action and will be 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 action will be handled by the backend or client. 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 will be 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.

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): 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 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 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 used to separate blocks.

Properties

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

Inherited properties

Inherited from Snap:

type (required): 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 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.

Inherited properties

Inherited from Snap:

type (required): 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.

1 {
2   "elements": [
3     {
4       "elements": [
5         {
6           "alt_text": "My heart goes",
7           "image_url": "https://media1.giphy.com/media/5kq0GCjHA8Rwc/giphy.gif?cid=ecf05e47uvd6y50d5jrxs2odyj0y90oq2v6hd6xz6j578183&rid=giphy.gif&ct=g",
8           "type": "image"
9         }
10       ],
11       "type": "content"
12     }
13   ],
14   "type": "card"
15 }

Plain text

A plain text element used to define unformatted text.

Properties

text (required): The plain text content.

Inherited properties

Inherited from Snap:

type (required): 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 used to define formatted text.

Properties

text (required): The rich text content.

Inherited properties

Inherited from Snap:

type (required): 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 is 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 stack of checkboxes, of type Plain Text Option.
initial_options (optional): The initially selected options.

Inherited properties

Inherited from Snap:

type (required): 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 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 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): 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 will be 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 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): 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 will be 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 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): 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 will be 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 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): 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 will be 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 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 list input type, see below.
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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 will be 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): 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 rev user includes these keywords in a Slack message, they will be 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.

Screenshot of a multiline string list input

1 {
2   "element": {
3     "action_id": "multiline",
4     "max_items": 2,
5     "min_items": 1,
6     "multiline": true,
7     "placeholder": {
8       "text": "Add keyword here",
9       "type": "plain_text"
10     },
11     "type": "string_list"
12   },
13   "hint": {
14     "text": "When a rev user includes these multiline keywords in a Slack message, they will be 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 will be 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 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): 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 will be 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 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 emails input allows users to enter a list of emails. Works with Input Layout blocks.

Inherited Properties

Inherited from Snap:

type (required): 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 will 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 will be 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 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 will be 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 will be 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 will be 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 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): 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 will be 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 will be 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 will be 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 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 will appear in 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 will be 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 will be 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 buttons 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 will be 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 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): 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 will be 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 will be 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 will be 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 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 will be 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 will be 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 will be 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 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 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 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 will be 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): 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 will be 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 will be 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 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): 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 will be 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 card which 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 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 ]

Content

A content block is used to hold various types of content. It contains an array of elements.

Properties

elements (required): An array of elements. See list of allowed elements below.

Inherited Properties

Inherited from Snap:

type (required): Type of the content component, should be set to "content".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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:

Plain Text
Rich Text
Image
Content
Divider

Example

1 {
2   "elements": [
3     {
4       "text": "Hello this is an example of content",
5       "type": "plain_text"
6     },
7     {
8       "alt_text": "My heart goes",
9       "image_url": "https://media1.giphy.com/media/5kq0GCjHA8Rwc/giphy.gif?cid=ecf05e47uvd6y50d5jrxs2odyj0y90oq2v6hd6xz6j578183&rid=giphy.gif&ct=g",
10       "type": "image"
11     }
12   ],
13   "type": "content"
14 }

Form

A form block that collects information from users.

Properties

elements (required): An array of elements. See list of allowed elements below.
submit_action (required): A button that can be clicked to submit the form.

Inherited Properties

Inherited from Snap:

type (required): Type of the form component, should be set to "form".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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 will be 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 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:

Input Layout
Divider

Example

A form composed of plain text inputs, number inputs, checkboxes, radio buttons, static select and multi static select snaps.

1 {
2   "action_id": "user_form",
3   "elements": [
4     {
5       "element": {
6         "action_id": "name",
7         "action_type": "remote",
8         "min_length": 10,
9         "placeholder": {
10           "text": "Enter your name",
11           "type": "plain_text"
12         },
13         "type": "plain_text_input"
14       },
15       "hint": {
16         "text": "Please enter your name",
17         "type": "plain_text"
18       },
19       "label": {
20         "text": "User Name",
21         "type": "plain_text"
22       },
23       "optional": true,
24       "type": "input_layout"
25     },
26     {
27       "element": {
28         "action_id": "age",
29         "max_value": 120,
30         "min_value": 10,
31         "type": "number_input"
32       },
33       "label": {
34         "text": "Age",
35         "type": "plain_text"
36       },
37       "type": "input_layout"
38     },
39     {
40       "element": {
41         "action_id": "checkboxes",
42         "options": [
43           {
44             "description": {
45               "text": "Description for option 1",
46               "type": "plain_text"
47             },
48             "text": {
49               "text": "Option 1",
50               "type": "plain_text"
51             },
52             "value": "option_1"
53           },
54           {
55             "description": {
56               "text": "Description for option 1",
57               "type": "plain_text"
58             },
59             "text": {
60               "text": "Option 2",
61               "type": "plain_text"
62             },
63             "value": "option_2"
64           }
65         ],
66         "type": "checkboxes"
67       },
68       "type": "input_layout"
69     },
70     {
71       "element": {
72         "action_id": "radio_buttons",
73         "options": [
74           {
75             "description": {
76               "text": "Description for option 1",
77               "type": "plain_text"
78             },
79             "text": {
80               "text": "Radio Option 1",
81               "type": "plain_text"
82             },
83             "value": "radio_option_1"
84           },
85           {
86             "description": {
87               "text": "Description for option 1",
88               "type": "plain_text"
89             },
90             "text": {
91               "text": "RadioOption 2",
92               "type": "plain_text"
93             },
94             "value": "radio_option_2"
95           }
96         ],
97         "type": "radio_buttons"
98       },
99       "type": "input_layout"
100     },
101     {
102       "element": {
103         "action_id": "multi_static_select",
104         "options": [
105           {
106             "text": {
107               "text": "Select option 1",
108               "type": "plain_text"
109             },
110             "value": "select-option-1"
111           },
112           {
113             "text": {
114               "text": "Select option 2",
115               "type": "plain_text"
116             },
117             "value": "select-option-2"
118           }
119         ],
120         "type": "multi_static_select"
121       },
122       "label": {
123         "text": "Multi Select",
124         "type": "plain_text"
125       },
126       "type": "input_layout"
127     },
128     {
129       "element": {
130         "action_id": "single_static_select",
131         "initial_selected_option": {
132           "text": {
133             "text": "Single 1",
134             "type": "plain_text"
135           },
136           "value": "single-option-1"
137         },
138         "options": [
139           {
140             "text": {
141               "text": "Single 1",
142               "type": "plain_text"
143             },
144             "value": "single-option-1"
145           },
146           {
147             "text": {
148               "text": "Single 2",
149               "type": "plain_text"
150             },
151             "value": "single-option-2"
152           }
153         ],
154         "placeholder": {
155           "text": "Placeholder here",
156           "type": "plain_text"
157         },
158         "type": "static_select"
159       },
160       "label": {
161         "text": "Single Select",
162         "type": "plain_text"
163       },
164       "type": "input_layout"
165     }
166   ],
167   "submit_action": {
168     "action_id": "submit",
169     "style": "primary",
170     "text": {
171       "text": "Submit",
172       "type": "plain_text"
173     },
174     "type": "button",
175     "value": "submit"
176   },
177   "type": "form"
178 }

Action Payload

Inherits type, action_id, action_type and timestamp from Base Payload, type will be set to "form".

1 {
2   "type": "form",
3   "action_id": "<the action identifier of the form>",
4   "action_type": "<the type of the action as defined in the Snap>",
5   "timestamp": "<timestamp as string in ISO 8601 format>",
6   "value": "<an object containing action payloads of nested Snaps>"
7 }

Example Payload

1 {
2   "action_id": "user_form",
3   "action_type": "remote",
4   "type": "form",
5   "value": {
6     "name": {
7       "action_id": "name",
8       "type": "plain_text_input",
9       "value": "Chuck Norris"
10     },
11     "age": { "action_id": "age", "type": "number_input", "value": "83" },
12     "checkboxes": {
13       "action_id": "checkboxes",
14       "type": "checkboxes",
15       "value": [
16         {
17           "description": {
18             "text": "Description for option 1",
19             "type": "plain_text"
20           },
21           "text": { "text": "Option 1", "type": "plain_text" },
22           "value": "option_1"
23         },
24         {
25           "description": {
26             "text": "Description for option 1",
27             "type": "plain_text"
28           },
29           "text": { "text": "Option 2", "type": "plain_text" },
30           "value": "option_2"
31         }
32       ]
33     },
34     "radio_buttons": {
35       "action_id": "radio_buttons",
36       "type": "radio_buttons",
37       "value": {
38         "description": {
39           "text": "Description for option 1",
40           "type": "plain_text"
41         },
42         "text": { "text": "RadioOption 2", "type": "plain_text" },
43         "value": "radio_option_2"
44       }
45     },
46     "multi_static_select": {
47       "action_id": "multi_static_select",
48       "type": "multi_static_select",
49       "value": [
50         {
51           "text": { "text": "Select option 1", "type": "plain_text" },
52           "value": "select-option-1"
53         },
54         {
55           "text": { "text": "Select option 2", "type": "plain_text" },
56           "value": "select-option-2"
57         }
58       ]
59     },
60     "single_static_select": {
61       "action_id": "single_static_select",
62       "type": "static_select",
63       "value": {
64         "text": { "text": "Single 1", "type": "plain_text" },
65         "value": "single-option-1"
66       }
67     }
68   },
69   "timestamp": "2023-07-12T08:26:10.842Z"
70 }

Input Layout

A layout that holds the elements which user can interact with in a form. Works with Form blocks.

Properties

element (required): The input element. See list of allowed elements below.
label (optional): A Plain Text element that defines the label shown above the input element.
hint (optional): A Plain Text element that defines the hint shown below the label.
optional (optional): A boolean that indicates whether the input element may be empty when a user submits the modal. For toggle, if this value is false, then it needs to be always toggled (needs to be true). Defaults to false.
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): Type of the input layout component, should be set to "input_layout".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be generated.

Example

1 {
2   "action_id": "user_form",
3   "alignment": "end",
4   "direction": "row",
5   "elements": [
6     {
7       "element": {
8         "action_id": "name",
9         "min_length": 10,
10         "placeholder": {
11           "text": "Enter your name",
12           "type": "plain_text"
13         },
14         "type": "plain_text_input"
15       },
16       "label": {
17         "text": "User Name",
18         "type": "plain_text"
19       },
20       "optional": true,
21       "type": "input_layout"
22     },
23     {
24       "element": {
25         "action_id": "age",
26         "max_value": 120,
27         "min_value": 10,
28         "type": "number_input"
29       },
30       "label": {
31         "text": "Age",
32         "type": "plain_text"
33       },
34       "type": "input_layout"
35     }
36   ],
37   "justify": "between",
38   "submit_action": {
39     "action_id": "submit",
40     "style": "primary",
41     "text": {
42       "text": "Submit",
43       "type": "plain_text"
44     },
45     "type": "button",
46     "value": "submit"
47   },
48   "type": "form"
49 }

Data Pickers

Part Picker

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

Properties

initial_parts_selected_options (optional): The initially selected parts, a list of DONv2 IDs.
max_selected_items (optional): The maximum number of parts that can be selected.
allowed_part_types (optional): A list of part types that are selectable from the list of parts in the dropdown. Possible values: "capability", "component", "custom_part", "enhancement", "feature", "linkable", "microservice", "product", "runnable".

Inherited Properties

Inherited from Snap:

type (required): Type of the part picker component, should be set to "part_picker".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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 will be 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 Disabled:

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

Example

Part picker snap with 2 selected parts.

1 {
2   "element": {
3     "action_id": "part_picker",
4     "action_type": "remote",
5     "max_selected_items": 5,
6     "type": "part_picker"
7   },
8   "label": {
9     "text": "Part",
10     "type": "plain_text"
11   },
12   "type": "input_layout"
13 }

Action Payload

Inherits type, action_id, action_type and timestamp from Base Payload, type will be set to "part_picker".

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

Example Payload

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

Tag Picker

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

Properties

initial_tags_selected_options (optional): The initially selected tags, a list of DONv2 IDs.
max_selected_items (optional): The maximum number of tags that can be selected.

Inherited Properties

Inherited from Snap:

type (required): Type of the tag picker component, should be set to "tag_picker".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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 will be 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

Tag picker snap with 1 selected tag.

1 {
2   "element": {
3     "action_id": "tag_picker",
4     "action_type": "remote",
5     "max_selected_items": 5,
6     "type": "tag_picker"
7   },
8   "label": {
9     "text": "Tag",
10     "type": "plain_text"
11   },
12   "type": "input_layout"
13 }

Action Payload

Inherits type, action_id, action_type and timestamp from Base Payload, type will be set to "tag_picker".

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

Example Payload

1 {
2   "action_id": "tag_picker",
3   "action_type": "remote",
4   "type": "tag_picker",
5   "value": ["don:core:dvrv-us-1:devo/H66a8LUt:tag/7"],
6   "timestamp": "2023-07-12T08:32:15.001Z"
7 }

User Picker

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

Properties

user_types (optional): The types of users that are allowed to be selected. Defaults to ["rev_user", "dev_user"]. Possible values: "rev_user", "dev_user", "sys_user".
initial_rev_users_selected_options (optional): The initially selected rev users, a list of DONv2 IDs.
initial_dev_users_selected_options (optional): The initially selected dev users, a list of DONv2 IDs.
initial_sys_users_selected_options (optional): The initially selected sys users, a list of DONv2 IDs.
max_selected_items (optional): The maximum number of users that can be selected.

Inherited Properties

Inherited from Snap:

type (required): Type of the user picker component, should be set to "user_picker".
block_id (optional): A unique identifier for the snap. If not provided, a random ID will be 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 will be 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

User picker snap with 1 selected user.

1 {
2   "element": {
3     "action_id": "user_picker",
4     "action_type": "remote",
5     "max_selected_items": 5,
6     "type": "user_picker"
7   },
8   "label": {
9     "text": "User",
10     "type": "plain_text"
11   },
12   "type": "input_layout"
13 }

Action Payload

Inherits type, action_id, action_type and timestamp from Base Payload, type will be set to "user_picker".

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

Example Payload

1 {
2   "action_id": "user_picker",
3   "action_type": "remote",
4   "type": "user_picker",
5   "value": ["don:identity:dvrv-us-1:devo/H66a8LUt:devu/5"],
6   "timestamp": "2023-07-12T08:32:15.001Z"
7 }

Example snap-kit

In this updated JSON, the divider component is added to create a visual separation. The checkboxes component allows for selecting multiple options. The part_picker component allows for selecting parts, and the tag_picker component allows for selecting tags. You can customize the options, initial selections, and other values according to your requirements.

1 {
2   "object": "source_id",
3   "body": "Giphy",
4   "type": "timeline_comment",
5   "snap_kit_body": {
6     "snap_in_id": "snap_in_id",
7     "snap_in_action_name": "giphy",
8     "body": {
9       "snaps": [
10         {
11           "type": "card",
12           "title": {
13             "text": "Hip hip hurray!",
14             "type": "plain_text"
15           },
16           "elements": [
17             {
18               "type": "content",
19               "elements": [
20                 {
21                   "type": "image",
22                   "image_url": "https://example.com/image.jpg",
23                   "alt_text": "Awesome GIF"
24                 }
25               ]
26             },
27             {
28               "type": "divider"
29             },
30             {
31               "type": "checkboxes",
32               "options": [
33                 {
34                   "text": {
35                     "text": "Option 1",
36                     "type": "plain_text"
37                   },
38                   "value": "option1"
39                 },
40                 {
41                   "text": {
42                     "text": "Option 2",
43                     "type": "plain_text"
44                   },
45                   "value": "option2"
46                 }
47               ]
48             },
49             {
50               "type": "part_picker",
51               "initial_parts_selected_options": ["part1"],
52               "max_selected_items": 2
53             },
54             {
55               "type": "tag_picker",
56               "initial_tags_selected_options": ["tag1"],
57               "max_selected_items": 3
58             },
59             {
60               "type": "actions",
61               "direction": "row",
62               "justify": "center",
63               "elements": [
64                 {
65                   "type": "button",
66                   "action_id": "send",
67                   "action_type": "remote",
68                   "style": "primary",
69                   "text": {
70                     "text": "Send",
71                     "type": "plain_text"
72                   },
73                   "value": "send"
74                 },
75                 {
76                   "type": "button",
77                   "action_id": "shuffle",
78                   "action_type": "remote",
79                   "style": "primary",
80                   "text": {
81                     "text": "Shuffle",
82                     "type": "plain_text"
83                   },
84                   "value": "shuffle"
85                 },
86                 {
87                   "type": "button",
88                   "action_id": "cancel",
89                   "action_type": "remote",
90                   "style": "danger",
91                   "text": {
92                     "text": "Cancel",
93                     "type": "plain_text"
94                   },
95                   "value": "cancel"
96                 }
97               ]
98             }
99           ]
100         }
101       ]
102     }
103   }
104 }

Snap-kit

Understanding the structure

Snap-kit body

Body

Snaps

Base types

User interface elements

Form elements

Layout elements

Data pickers

Action payloads

Base Payload

Base Types

Snap

Properties

Action

Action Types

Properties

Inherited properties

Focusable

Properties

Placeholder

Properties

Disabled

Properties

Layout

Properties

User interface elements

Button

Properties

Inherited properties

Example

Action payload

Example payload

Divider

Properties

Inherited properties

Example

Image

Properties

Inherited properties

Example

Plain text

Properties

Inherited properties

Example

Rich text

Properties

Inherited properties

Example

Form elements

Plain text option

Checkboxes

Properties

Inherited properties

Example

Action payload

Example payload

Input

Properties

Inherited properties

Plain text input

Inherited properties

Additional properties

Example

Action payload

Example payload

Number input

Inherited properties

Additional properties

Example

Action payload

Example payload

Email input

Inherited properties

Additional properties

Example

Action payload

Example payload

Rich text input