feedback from PR

docs/content/concepts/action-listening.md → docs/content/concepts/actions.md

@@ -1,21 +1,17 @@
 ---
-title: Listening to actions
+title: Listening & responding to actions
 lang: en
-slug: /concepts/action-listening
+slug: /concepts/actions
 ---
 
-Your app can listen to user actions like button clicks, and menu selects, using the `action` method.
+Your app can listen and respond to user actions like button clicks, and menu selects, using the `action` method.
+
+## Listening to actions
 
 Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
 
 You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests section](/concepts/acknowledge).
 
-:::info
-
-Since v2, message shortcuts (previously message actions) now use the `shortcut()` method instead of the `action()` method. View the [migration guide for V2](/migration/migration-v2) to learn about the changes.
-
-:::
-
 View more information about the `block_actions` payload within the [relevant API documentation page](https://api.slack.com/reference/interaction-payloads). To access the full payload of a view from within a listener, reference the `body` argument within your callback function.
 
 ```javascript
@@ -26,10 +22,7 @@ app.action('approve_button', async ({ ack }) => {
 });
 ```
 
-<details>
-<summary>
-Listening to actions using a constraint object
-</summary>
+### Listening to actions using a constraint object
 
 You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type string or RegExp object.
 
@@ -56,4 +49,32 @@ app.action({ action_id: 'select_user', block_id: 'assign_ticket' },
   });
 ```
 
-</details>
+## Responding to actions
+
+There are two main ways to respond to actions. The first (and most common) way is to use the `say` function. The `say` function sends a message back to the conversation where the incoming request took place.
+
+The second way to respond to actions is using `respond()`, which is a simple utility to use the `response_url` associated with an action.
+
+```javascript
+// Your middleware will be called every time an interactive component with the action_id “approve_button” is triggered
+app.action('approve_button', async ({ ack, say }) => {
+  // Acknowledge action request
+  await ack();
+  await say('Request approved 👍');
+});
+```
+
+
+### Using the `respond()` utility 
+
+Since `respond()` is a utility for calling the `response_url`, it behaves in the same way. You can pass a JSON object with a new message payload that will be published back to the source of the original interaction with optional properties like `response_type` (which has a value of `in_channel` or `ephemeral`), `replace_original`, and `delete_original`.
+
+```javascript
+// Listens to actions triggered with action_id of “user_select”
+app.action('user_select', async ({ action, ack, respond }) => {
+  await ack();
+  if (action.type === 'users_select') {
+    await respond(`You selected <@${action.selected_user}>`);
+  }
+});
+```

docs/content/concepts/commands.md

@@ -1,5 +1,5 @@
 ---
-title: Listening and responding to commands
+title: Listening & responding to commands
 lang: en
 slug: /concepts/commands
 ---
@@ -14,7 +14,7 @@ If you use `command()` multiple times with overlapping RegExp matches, _all_ mat
 
 Commands must be acknowledged with `ack()` to inform Slack your app has received the request.
 
-There are two ways to respond to slash commands. The first way is to use `say()`, which accepts a string or JSON payload. The second is `respond()` which is a utility for the `response_url`. These are explained in more depth in the [responding to actions](/concepts/action-respond) section.
+There are two ways to respond to slash commands. The first way is to use `say()`, which accepts a string or JSON payload. The second is `respond()` which is a utility for the `response_url`. These are explained in more depth in the [responding to actions](/concepts/actions) section.
 
 When configuring commands within your app configuration, you'll continue to append `/slack/events` to your request URL.
 

docs/content/concepts/custom-steps.md

@@ -68,7 +68,7 @@ Example app manifest definition
 
 Your app's custom steps may create interactivity points for users, for example: Post a message with a button
 
-If such interaction points originate from a custom step execution, the events sent to your app representing the end-user interaction with these points are considered to be _function-scoped interactivity events_. These interactivity events can be handled by your app using the same concepts we covered earlier, such as [Listening to actions](/concepts/action-listening).
+If such interaction points originate from a custom step execution, the events sent to your app representing the end-user interaction with these points are considered to be _function-scoped interactivity events_. These interactivity events can be handled by your app using the same concepts we covered earlier, such as [Listening to actions](/concepts/actions).
 
 _function-scoped interactivity events_ will contain data related to the custom step (`function_executed` event) they were spawned from, such as custom step `inputs` and access to `complete()` and `fail()` listener arguments.
 

docs/content/concepts/error-handling.md

@@ -6,7 +6,7 @@ slug: /concepts/error-handling
 
 :::info
 
-Since v2, error handling has improved! View the [migration guide for V2](/migration/migration-v2) to learn about the changes.
+Since v2, error handling has improved! View the [migration guide for V2](/tutorial/migration-v2) to learn about the changes.
 
 :::
 

docs/content/concepts/event-listening.md

@@ -25,29 +25,4 @@ app.event('team_join', async ({ event, client, logger }) => {
     logger.error(error);
   }
 });
-```
-
-<details>
-<summary>
-Filtering on message subtypes
-</summary>
-
-A `message()` listener is equivalent to `event('message')`
-
-You can filter on subtypes of events by using the built-in `subtype()` middleware. Common message subtypes like `message_changed` and `message_replied` can be found [on the message event page](https://api.slack.com/events/message#message_subtypes).
-
-```javascript
-// Import subtype from the package
-const { App, subtype } = require('@slack/bolt');
-
-// Matches all message changes from users
-app.message(subtype('message_changed'), ({ event, logger }) => {
-  // This if statement is required in TypeScript code
-  if (event.subtype === 'message_changed'
-    && !event.message.subtype
-    && !event.previous_message.subtype) {
-    logger.info(`The user ${event.message.user} changed their message from ${event.previous_message.text} to ${event.message.text}`);
-  }
-});
-```
-</details>
+```