@slack/interactive-messages - npm Package Compare versions

Comparing version 1.0.2 to 1.1.0

package.json

 {
   "name": "@slack/interactive-messages",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Slack Interactive Messages module",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

@@ -6,15 +6,19 @@ # Slack Interactive Messages for Node
 
-Build your Slack Apps with rich and engaging user interactions using buttons, menus, and dialogs.
-The package will help you start with sensible and secure defaults.
+Build your Slack Apps with rich and engaging user interactions using block actions, buttons, menus, 
+and dialogs. The package will help you start with sensible and secure defaults.
 
 The adapter gives you a meaningful API to handle actions from all of Slack's interactive
-message components ([buttons](https://api.slack.com/docs/message-buttons),
-[menus](https://api.slack.com/docs/message-menus), and [dialogs](https://api.slack.com/dialogs)).
-Use it as an independent HTTP server or plug it into an existing server as
-[Express](http://expressjs.com/) middleware.
+message components
+[actions block elements](https://api.slack.com/reference/messaging/interactive-components),
+([buttons](https://api.slack.com/docs/message-buttons),
+[menus](https://api.slack.com/docs/message-menus),
+and [dialogs](https://api.slack.com/dialogs)). Use it as an independent HTTP server or plug it into
+an existing server as [Express](http://expressjs.com/) middleware.
 
-This package does **not** help you compose messages with buttons, menus and dialogs to trigger the
-actions. We recommend using the [Message Builder](https://api.slack.com/docs/messages/builder) to
-design interactive messages. You can send these messages to Slack using the Web API, Incoming
-Webhooks, and other parts of the platform.
+This package does **not** help you compose messages with action blocks, buttons, menus and dialogs
+to trigger the actions. We recommend using the
+[Block Kit Builder](https://api.slack.com/tools/block-kit-builder) to design interactive Block Kit
+messages and the [Message Builder](https://api.slack.com/docs/messages/builder) to design legacy
+interactive messages. You can send these messages to Slack using the Web API, Incoming Webhooks,
+and other parts of the platform.
 
@@ -163,2 +167,5 @@ *  [Installation](#installation)
 ```
+> ⚠️ If your app is using [blocks](https://api.slack.com/messaging/composing/layouts), you _must_
+use an object to describe constraints (`block_id` and `action_id`). Blocks have no `callback_id`.
+There are examples below.
 
@@ -187,2 +194,25 @@ Use an object to describe other constraints, even combine multiple constraints to create more
 
+#### Action matching with blocks
+
+Apps using [blocks](https://api.slack.com/messaging/composing/layouts) must use an object to
+describe constraints since they contain no `callback_id`. Instead, you can use the `block_id` and
+`action_id` described in the [interactive component documentation](https://api.slack.com/reference/messaging/interactive-components).
+
+```javascript
+// Run handlerFunction for a any interactions with a block_id of 'save'
+slackInteractions.action({ blockId: 'save' }, handlerFunction);
+
+// Run handlerFunction for a any interactions with an action_id of 'select_coffee'
+slackInteractions.action({ actionId: 'select_coffee' }, handlerFunction);
+
+// Run handlerFunction for a static select element with an action_id of 'select_animal'
+slackInteractions.action({ actionId: 'select_animal', type: 'static_select' }, handlerFunction);
+
+// This function is discussed in "Responding to actions" below
+function handlerFunction() {
+}
+```
+
+Blocks are not supported in dialogs or message actions, so you cannot filter by those types.
+
 #### Responding to actions
@@ -193,6 +223,6 @@
 
-For most actions (button presses, menu selections, and message actions), a response is simply an
-updated message to replace the one where the interaction occurred. Your app can return a message
-(or a Promise for a message) from the handler. **We recommend that apps at least remove the
-interactive elements from the message in the response** so that users don't get confused (for
+For most actions (block actions, button presses, menu selections, and message actions), a response
+is simply an updated message to replace the one where the interaction occurred. Your app can return
+a message (or a Promise for a message) from the handler. **We recommend that apps at least remove
+the interactive elements from the message in the response** so that users don't get confused (for
 example, click the same button twice). Find details about the format for a message in the docs for
@@ -206,2 +236,6 @@ [message](https://api.slack.com/docs/interactive-message-field-guide#message).
 
+> ⚠️ If your app is using [blocks](https://api.slack.com/messaging/composing/layouts), your payload
+will look different. You can find the payload for action block interactivity on the
+[interactive components](https://api.slack.com/reference/messaging/interactive-components) page.
+
 If your app defers some work asynchronously (like querying another API or using a database), you can
@@ -259,3 +293,3 @@ continue to update the message using the `respond()` function that is provided to your handler.
 but rather the response tells Slack whether the inputs are valid and the dialog can be closed on
-the user's screen. Your app returns a list of errors (or a Promise for a list of errors) from the
+the user's screen. Your app returns an object with a list of errors as a property (or a Promise for an object with a list of errors as a property) from the
 handler. If there are no errors, your app should return nothing from the handler. Find more details
@@ -267,3 +301,3 @@ on the structure of the list of errors in the docs for
 conversation where the dialog was triggered. **We recommend that apps use `respond()` to notify the
-user that the dialog submission was recieved** and use it again to communicate updates such as
+user that the dialog submission was received** and use it again to communicate updates such as
 success or failure.
@@ -278,3 +312,4 @@
 
-  // Check the values in `payload.submission` and report any possible errors
+  // Check the values in `payload.submission` and report any possible errors 
+  //   in the format {errors: [{name:'username', error:'Uh-oh. This username has been taken!'}]}
   const errors = validateOrderSubmission(payload.submission);
@@ -332,2 +367,6 @@ if (errors) {
 
+> ⚠️ If your app is using [blocks](https://api.slack.com/messaging/composing/layouts), you _must_
+use an object to describe contraints (`block_id` and `action_id`). Blocks have no `callback_id`.
+There are examples below.
+
 Use an object to describe other constraints, even combine multiple constraints to create more
@@ -349,2 +388,18 @@ specific handlers. The full set of constraint options are described in the
 
+#### Options request matching with blocks
+
+Use an object to describe constraints if your app is using blocks.
+
+```javascript
+// Run handlerFunction for all options requests from inside a message with blocks
+slackInteractions.options({ within: 'block_actions' }, handlerFunction)
+
+// Run handlerFunction for all options requests from inside a message with blocks with block_id of 'coffee_menu'
+slackInteractions.options({ blockId: 'coffee_menu', within: 'block_actions' }, handlerFunction)
+
+// This function is discussed in "Responding to options requests" below
+function handlerFunction() {
+}
+```
+
 #### Responding to options requests
@@ -351,0 +406,0 @@

No alert changes

Improved metrics

Number of lines in readme file

467

increased by13.35%

Worsened metrics

Total package byte prevSize

171707

decreased by-1.49%

Number of package files

11

decreased by-15.38%

Lines of code

1030

decreased by-4.54%

No dependency changes