Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: concept focused nav #2302

Merged
merged 9 commits into from
Oct 29, 2024
Prev Previous commit
Next Next commit
feedback from PR
lukegalbraithrussell committed Oct 28, 2024
commit 4041ac638198fa1d71344b5febe9aedf3049fefc
36 changes: 0 additions & 36 deletions docs/content/concepts/action-respond.md

This file was deleted.

Original file line number Diff line number Diff line change
@@ -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}>`);
}
});
```
186 changes: 0 additions & 186 deletions docs/content/concepts/assistant.md

This file was deleted.

4 changes: 2 additions & 2 deletions docs/content/concepts/commands.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there some end-user or api.slack.com document we can link to for Slash Commands?

Original file line number Diff line number Diff line change
@@ -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.

2 changes: 1 addition & 1 deletion docs/content/concepts/custom-steps.md
Original file line number Diff line number Diff line change
@@ -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.

2 changes: 1 addition & 1 deletion docs/content/concepts/error-handling.md
Original file line number Diff line number Diff line change
@@ -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.

:::

27 changes: 1 addition & 26 deletions docs/content/concepts/event-listening.md
Original file line number Diff line number Diff line change
@@ -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>
```
Loading