From 60c673a5a8f6be1a3709e8179795095992752859 Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Tue, 29 Oct 2024 12:27:22 -0700 Subject: [PATCH 1/3] docs: cleanup --- docs/content/concepts/actions.md | 1 - docs/content/concepts/authorization.md | 6 +- docs/content/concepts/custom-routes.md | 9 +- docs/content/concepts/custom-steps.md | 14 +-- .../concepts/deferring-initialization.md | 2 +- docs/content/concepts/error-handling.md | 8 +- docs/content/concepts/listener-middleware.md | 2 +- docs/content/concepts/logging.md | 6 +- docs/content/concepts/message-sending.md | 8 +- docs/content/concepts/receiver.md | 2 +- docs/content/concepts/select-menu-options.md | 2 +- docs/content/concepts/shortcuts.md | 98 ++++++++--------- docs/content/concepts/socket-mode.md | 9 +- .../concepts/updating-pushing-views.md | 10 +- docs/content/concepts/view-submissions.md | 6 +- docs/content/concepts/web-api.md | 4 +- docs/content/deployments/aws-lambda.md | 56 +++++----- docs/content/deployments/heroku.md | 35 +++--- docs/content/getting-started.mdx | 7 +- docs/content/legacy/conversation-store.md | 4 +- docs/content/legacy/hubot-migration.md | 35 +++--- docs/content/legacy/steps-from-apps.md | 2 +- docs/content/migration/migration-v2.md | 26 ++--- docs/content/migration/migration-v3.md | 20 ++-- docs/content/migration/migration-v4.md | 26 ++--- docs/docusaurus.config.js | 3 +- .../current/concepts/actions.md | 6 +- .../current/concepts/authenticating-oauth.md | 8 +- .../current/concepts/custom-routes.md | 8 +- .../current/concepts/error-handling.md | 9 +- .../current/concepts/global-middleware.md | 6 +- .../current/concepts/listener-middleware.md | 6 +- .../current/concepts/logging.md | 9 +- .../current/concepts/message-listening.md | 2 - .../current/concepts/message-sending.md | 8 +- .../current/concepts/shortcuts.md | 101 ++++++++---------- .../current/concepts/socket-mode.md | 9 +- .../concepts/updating-pushing-views.md | 6 +- .../current/concepts/view-submissions.md | 4 +- .../current/concepts/web-api.md | 2 +- .../current/deployments/aws-lambda.md | 53 +++++---- .../current/deployments/heroku.md | 39 ++++--- .../current/getting-started.mdx | 18 ++-- .../current/legacy/hubot-migration.md | 69 ++++++++---- .../current/legacy/steps-from-apps.md | 2 +- .../current/migration/migration-v2.md | 22 ++-- .../current/migration/migration-v3.md | 17 ++- .../current/reference.md | 11 +- 48 files changed, 379 insertions(+), 437 deletions(-) diff --git a/docs/content/concepts/actions.md b/docs/content/concepts/actions.md index d64cfc780..65b98be2b 100644 --- a/docs/content/concepts/actions.md +++ b/docs/content/concepts/actions.md @@ -64,7 +64,6 @@ app.action('approve_button', async ({ ack, say }) => { }); ``` - ### 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`. diff --git a/docs/content/concepts/authorization.md b/docs/content/concepts/authorization.md index 56faea126..ce6c69b80 100644 --- a/docs/content/concepts/authorization.md +++ b/docs/content/concepts/authorization.md @@ -6,7 +6,11 @@ slug: /concepts/authorization Authorization is the process of deciding which Slack credentials (such as a bot token) should be available while processing a specific incoming request. -Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead. If you're using the [built-in OAuth support](/concepts/authenticating-oauth) authorization is handled by default, so you do not need to pass in an `authorize` option. +Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead. + +:::tip +If you're using the [built-in OAuth support](/concepts/authenticating-oauth) authorization is handled by default, so you do not need to pass in an `authorize` option. +::: The `authorize` option can be set to a function that takes an event source as its input, and should return a Promise for an object containing the authorized credentials. The source contains information about who and where the request is coming from by using properties like `teamId` (always available), `userId`, `conversationId`, and `enterpriseId`. diff --git a/docs/content/concepts/custom-routes.md b/docs/content/concepts/custom-routes.md index d4bc7595f..e776088e1 100644 --- a/docs/content/concepts/custom-routes.md +++ b/docs/content/concepts/custom-routes.md @@ -48,11 +48,7 @@ const app = new App({ })(); ``` -
- -Custom ExpressReceiver routes - - +## Custom ExpressReceiver routes Adding custom HTTP routes is quite straightforward when using Bolt’s built-in ExpressReceiver. Since `v2.1.0`, `ExpressReceiver` added a `router` property, which exposes the Express [Router](http://expressjs.com/en/4x/api.html#router) on which additional routes and middleware can be added. @@ -91,5 +87,4 @@ receiver.router.post('/secret-page', (req, res) => { await app.start(); console.log('⚡️ Bolt app started'); })(); -``` -
+``` \ No newline at end of file diff --git a/docs/content/concepts/custom-steps.md b/docs/content/concepts/custom-steps.md index f54c01cd1..084a958f7 100644 --- a/docs/content/concepts/custom-steps.md +++ b/docs/content/concepts/custom-steps.md @@ -29,10 +29,7 @@ app.function('sample_custom_step', async ({ inputs, complete, fail, logger }) => }); ``` -
- -Example app manifest definition - +### Example app manifest definition ```json ... @@ -60,8 +57,6 @@ Example app manifest definition } ``` -
- --- ## Listening to custom step interactivity events @@ -131,10 +126,7 @@ app.action('sample_button', async ({ ack, body, client, complete, fail, logger } }); ``` -
- -Example app manifest definition - +### Example app manifest definition ```json ... @@ -162,6 +154,4 @@ Example app manifest definition } ``` -
- Learn more about responding to interactivity, see the [Slack API documentation](https://api.slack.com/automation/functions/custom-bolt#interactivity). diff --git a/docs/content/concepts/deferring-initialization.md b/docs/content/concepts/deferring-initialization.md index 303eae4b9..fcc06a0c1 100644 --- a/docs/content/concepts/deferring-initialization.md +++ b/docs/content/concepts/deferring-initialization.md @@ -8,7 +8,7 @@ Bolt offers a way to defer full initialization via the `deferInitialization` opt :::info -If you call `start()` before `init()`, Bolt will raise an exception._ +If you call `start()` before `init()`, Bolt will raise an exception. ::: diff --git a/docs/content/concepts/error-handling.md b/docs/content/concepts/error-handling.md index 4cd94eaa7..653ebfbda 100644 --- a/docs/content/concepts/error-handling.md +++ b/docs/content/concepts/error-handling.md @@ -62,10 +62,7 @@ app.error(async (error) => { }); ``` -
- -Accessing more data in the error handler - +## Accessing more data in the error handler There may be cases where you need to log additional data from a request in the global error handler. Or you may simply wish to have access to the `logger` you've passed into Bolt. @@ -90,5 +87,4 @@ app.error(async ({ error, logger, context, body }) => { // Do something with the team's ID for debugging purposes } }); -``` -
+``` \ No newline at end of file diff --git a/docs/content/concepts/listener-middleware.md b/docs/content/concepts/listener-middleware.md index e7945449e..3040977e5 100644 --- a/docs/content/concepts/listener-middleware.md +++ b/docs/content/concepts/listener-middleware.md @@ -10,7 +10,7 @@ There’s a collection of [built-in listener middleware](/reference#built-in-lis But of course, you can write your own middleware for more custom functionality. While writing your own middleware, your function must call `await next()` to pass control to the next middleware, or `throw` to pass an error back up the previously-executed middleware chain. -As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware th +As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware that excludes any bot messages. ```javascript // Listener middleware that filters out messages with 'bot_message' subtype diff --git a/docs/content/concepts/logging.md b/docs/content/concepts/logging.md index 99291332c..515eafd26 100644 --- a/docs/content/concepts/logging.md +++ b/docs/content/concepts/logging.md @@ -18,10 +18,7 @@ const app = new App({ }); ``` -
- -Sending log output somewhere besides the console - +## Sending log output somewhere besides the console If you want to send logs to somewhere besides the console or want more control over the logger, you can implement a custom logger. A custom logger must implement specific methods (known as the `Logger` interface): @@ -57,4 +54,3 @@ const app = new App({ }, }); ``` -
diff --git a/docs/content/concepts/message-sending.md b/docs/content/concepts/message-sending.md index cbe4bc912..873ce1f11 100644 --- a/docs/content/concepts/message-sending.md +++ b/docs/content/concepts/message-sending.md @@ -15,10 +15,7 @@ app.message('knock knock', async ({ message, say }) => { }); ``` -
- -Sending a message with blocks - +## Sending a message with blocks `say()` accepts more complex message payloads to make it easy to add functionality and structure to your messages. @@ -48,5 +45,4 @@ app.event('reaction_added', async ({ event, say }) => { }); } }); -``` -
\ No newline at end of file +``` \ No newline at end of file diff --git a/docs/content/concepts/receiver.md b/docs/content/concepts/receiver.md index 3c1dcca47..ba99d8ad2 100644 --- a/docs/content/concepts/receiver.md +++ b/docs/content/concepts/receiver.md @@ -107,7 +107,7 @@ class SimpleReceiver { }) } - // This is a very simple implementation. Look at the ExpressReceiver source for more detail + // This is a simple implementation. Look at the ExpressReceiver source for more detail async requestHandler(req, res) { let ackCalled = false; // Assume parseBody function exists to parse incoming requests diff --git a/docs/content/concepts/select-menu-options.md b/docs/content/concepts/select-menu-options.md index 6589cd3d4..7acc2a27b 100644 --- a/docs/content/concepts/select-menu-options.md +++ b/docs/content/concepts/select-menu-options.md @@ -4,7 +4,7 @@ lang: en slug: /concepts/options --- -The `options()` method listens for incoming option request payloads from Slack. [Similar to `action()`](/concepts/actions), +The `options()` method listens for incoming option request payloads from Slack. Similar to the [`action()`](/concepts/actions) method, an `action_id` or constraints object is required. While it's recommended to use `action_id` for `external_select` menus, dialogs do not yet support Block Kit so you'll have to diff --git a/docs/content/concepts/shortcuts.md b/docs/content/concepts/shortcuts.md index 0c57d792e..3785065a3 100644 --- a/docs/content/concepts/shortcuts.md +++ b/docs/content/concepts/shortcuts.md @@ -76,59 +76,55 @@ app.shortcut('open_modal', async ({ shortcut, ack, client, logger }) => { }); ``` -
- - Listening to shortcuts using a constraint object - +## Listening to shortcuts using a constraint object - You can use a constraints object to listen to `callback_id` and `type` values. Constraints in the object can be of type string or RegExp object. +You can use a constraints object to listen to `callback_id` and `type` values. Constraints in the object can be of type string or RegExp object. - ```javascript - // Your middleware will only be called when the callback_id matches 'open_modal' AND the type matches 'message_action' - app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, client, logger }) => { - try { - // Acknowledge shortcut request - await ack(); - - // Call the views.open method using one of the built-in WebClients - const result = await client.views.open({ - trigger_id: shortcut.trigger_id, - view: { - type: "modal", - title: { - type: "plain_text", - text: "My App" - }, - close: { - type: "plain_text", - text: "Close" +```javascript +// Your middleware will only be called when the callback_id matches 'open_modal' AND the type matches 'message_action' +app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, client, logger }) => { + try { + // Acknowledge shortcut request + await ack(); + + // Call the views.open method using one of the built-in WebClients + const result = await client.views.open({ + trigger_id: shortcut.trigger_id, + view: { + type: "modal", + title: { + type: "plain_text", + text: "My App" + }, + close: { + type: "plain_text", + text: "Close" + }, + blocks: [ + { + type: "section", + text: { + type: "mrkdwn", + text: "About the simplest modal you could conceive of :smile:\n\nMaybe or ." + } }, - blocks: [ - { - type: "section", - text: { + { + type: "context", + elements: [ + { type: "mrkdwn", - text: "About the simplest modal you could conceive of :smile:\n\nMaybe or ." + text: "Psssst this modal was designed using " } - }, - { - type: "context", - elements: [ - { - type: "mrkdwn", - text: "Psssst this modal was designed using " - } - ] - } - ] - } - }); - - logger.info(result); - } - catch (error) { - logger.error(error); - } - }); - ``` -
\ No newline at end of file + ] + } + ] + } + }); + + logger.info(result); + } + catch (error) { + logger.error(error); + } +}); +``` diff --git a/docs/content/concepts/socket-mode.md b/docs/content/concepts/socket-mode.md index 2dc9e153c..a020723a9 100644 --- a/docs/content/concepts/socket-mode.md +++ b/docs/content/concepts/socket-mode.md @@ -23,10 +23,7 @@ const app = new App({ })(); ``` -
- -Custom SocketMode Receiver - +## Custom SocketMode Receiver You can define a custom `SocketModeReceiver` by importing it from `@slack/bolt`. @@ -53,6 +50,4 @@ const app = new App({ await app.start(); console.log('⚡️ Bolt app started'); })(); -``` - -
+``` \ No newline at end of file diff --git a/docs/content/concepts/updating-pushing-views.md b/docs/content/concepts/updating-pushing-views.md index 3ccf4f14a..3ba2a164b 100644 --- a/docs/content/concepts/updating-pushing-views.md +++ b/docs/content/concepts/updating-pushing-views.md @@ -4,15 +4,15 @@ lang: en slug: /concepts/updating-pushing-views --- -Modals contain a stack of views. When you call [`views.open`](https://api.slack.com/methods/views.open), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views.update`](https://api.slack.com/methods/views.update), or stack a new view on top of the root view by calling [`views.push`](https://api.slack.com/methods/views.push). +Modals contain a stack of views. When you call the [`views.open`](https://api.slack.com/methods/views.open) method, you add the root view to the modal. After the initial call, you can dynamically update a view by calling the [`views.update`](https://api.slack.com/methods/views.update) method, or stack a new view on top of the root view by calling the [`views.push`](https://api.slack.com/methods/views.push) method. -**`views.update`** +## The `views.update` method -To update a view, you can use the built-in client to call `views.update` with the `view_id` that was generated when you opened the view, and a new `view` including the updated `blocks` array. If you're updating the view when a user interacts with an element inside of an existing view, the `view_id` will be available in the `body` of the request. +To update a view, you can use the built-in client to call the `views.update` method with the `view_id` parameter that was generated when you opened the view, and a new `view` object including the updated `blocks` array. If you're updating the view when a user interacts with an element inside of an existing view, the `view_id` parameter will be available in the `body` of the request. -**`views.push`** +## The `views.push` method -To push a new view onto the view stack, you can use the built-in client to call `views.push` with a valid `trigger_id` a new [view payload](https://api.slack.com/reference/block-kit/views). The arguments for `views.push` is the same as [opening modals](/concepts/creating-modals). After you open a modal, you may only push two additional views onto the view stack. +To push a new view onto the view stack, you can use the built-in client to call the `views.push` method by passing a valid `trigger_id` parameter and a new [view payload](https://api.slack.com/reference/block-kit/views). The arguments for the `views.push` method is the same as [`views.open`](/concepts/creating-modals). After you open a modal, you may only push two additional views onto the view stack. Learn more about updating and pushing views in our [API documentation](https://api.slack.com/surfaces/modals/using#modifying) diff --git a/docs/content/concepts/view-submissions.md b/docs/content/concepts/view-submissions.md index 1a51d34c3..6ca0a9ed9 100644 --- a/docs/content/concepts/view-submissions.md +++ b/docs/content/concepts/view-submissions.md @@ -10,7 +10,7 @@ Slack will send a `view_submission` request when a user submits a view. To recei If the `notify_on_close` field of a view has been set to `true`, Slack will also send a `view_closed` request if a user clicks the close button. See the section on **Handling views on close** for more detail. To listen to either a `view_submission` request or `view_closed` request, you can use the built-in `view()` method. -`view()` requires a `callback_id` of type `string` or `RegExp` or a constraint object with properties `type` and `callback_id`. +The `view()` method requires a `callback_id` of type `string` or `RegExp` or a constraint object with properties `type` and `callback_id`. --- @@ -35,9 +35,11 @@ Read more about view submissions in our [API documentation](https://api.slack.co ## Handling views on close -💡 When listening for `view_closed` requests, you must pass an object containing `type: 'view_closed'` and the view `callback_id`. See below for an example of this: +When listening for `view_closed` requests, you must pass an object containing `type: 'view_closed'` and the view `callback_id`. See below for an example of this. +:::tip See the [API documentation](https://api.slack.com/surfaces/modals/using#modal_cancellations) for more information about `view_closed`. +::: #### Handle a `view_closed` request diff --git a/docs/content/concepts/web-api.md b/docs/content/concepts/web-api.md index 0e1b3cdbe..667378aef 100644 --- a/docs/content/concepts/web-api.md +++ b/docs/content/concepts/web-api.md @@ -8,9 +8,9 @@ You can call any [Web API method](https://api.slack.com/methods) using the [`Web Your Bolt app also has a top-level `app.client` which you can manually pass the `token` parameter. If the incoming request is not authorized or you're calling a method from outside of a listener, use the top-level `app.client`. -Calling one of the [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api)'s methods will return a Promise containing the response from Slack, regardless of whether you use the top-level or listener's client. +Calling one of the [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api) methods will return a Promise containing the response from Slack, regardless of whether you use the top-level or listener's client. -Since the introduction of [org wide app installations](https://api.slack.com/enterprise/apps), [some web-api methods](https://api.slack.com/enterprise/apps/changes-apis#methods) now require `team_id` to indicate which workspace to act on. Bolt for JavaScript will attempt to infer the `team_id` based on incoming payloads and pass it along to `client`. This is handy for existing applications looking to add support for org wide installations and not spend time updating all of these web-api calls. +Since the introduction of [org wide app installations](https://api.slack.com/enterprise/apps), [some web-api methods](https://api.slack.com/enterprise/apps/changes-apis#methods) now require a `team_id` parameter to indicate which workspace to act on. Bolt for JavaScript will attempt to infer the `team_id` value based on incoming payloads and pass it along to `client`. This is handy for existing applications looking to add support for org wide installations and not spend time updating all of these web-api calls. ```javascript // Unix Epoch time for September 30, 2019 11:59:59 PM diff --git a/docs/content/deployments/aws-lambda.md b/docs/content/deployments/aws-lambda.md index 0a5e0012b..ec56b6a70 100644 --- a/docs/content/deployments/aws-lambda.md +++ b/docs/content/deployments/aws-lambda.md @@ -19,7 +19,7 @@ Skip this section if you have already [configured a profile](https://docs.aws.am ::: -**1. Sign up for an AWS account** +### 1. Sign up for an AWS account If you don't already have an account, you should [sign up for AWS](https://aws.amazon.com/) and follow the on-screen instructions. @@ -29,25 +29,25 @@ You may be asked for payment information during the sign up. Don't worry, this g ::: -**2. Create an AWS access key** +### 2. Create an AWS access key Next, you'll need programmatic access to your AWS account to deploy onto Lambda. In the world of AWS, this requires an **Access Key ID** and **Secret Access Key**. We recommend watching this short, step-by-step video to 🍿 [create an IAM user and download the access keys](https://www.youtube.com/watch?v=KngM5bfpttA). -:::tip - - **Do you already have an IAM user?** Follow the official AWS guide to [create access keys for existing IAM users](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds). +:::tip[Do you already have an IAM user?] + +Follow the official AWS guide to [create access keys for existing IAM users](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds). ::: -**3. Install the AWS CLI** +### 3. Install the AWS CLI The AWS tools are available as a Command Line Interface (CLI) and can be [installed on macOS, Windows, or Linux](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html). On macOS, you can install the AWS CLI by [downloading the latest package installer](https://awscli.amazonaws.com/AWSCLIV2.pkg). -**4. Configure an AWS profile** +### 4. Configure an AWS profile You can use the AWS CLI to configure a profile that stores your access key pair on your local machine. This profile is used by the CLI and other tools to access AWS. @@ -75,8 +75,6 @@ That wraps up configuring your local machine to access AWS. 👏 Next, let's do The [Serverless Framework](https://serverless.com/) includes tools that let you easily configure, debug, and deploy your app to AWS Lambda. -**1. Install the Serverless Framework CLI** - The Serverless tools are available as a Command Line Interface (CLI) and can be installed on macOS, Windows, or Linux. Check out the [Serverless Getting Started documentation](https://www.serverless.com/framework/docs/getting-started/) for instructions on how to install. Once the installation is complete, test the Serverless CLI by displaying the commands available to you: @@ -109,7 +107,7 @@ Now that you have an app, let's prepare it for AWS Lambda and the Serverless Fra ## Prepare the app {#prepare-the-app} -**1. Prepare the app for AWS Lambda** +### 1. Prepare the app for AWS Lambda By default, our Bolt Getting Started app sample is configured to use SocketMode. Let's update the setup in `app.js` to have our app listen for HTTP requests instead. @@ -172,7 +170,7 @@ module.exports.handler = async (event, context, callback) => { When you're done, your app should look similar to the ⚡️[Deploying to AWS Lambda app](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-aws-lambda/app.js). -**2. Add a serverless.yml** +### 2. Add a serverless.yml Serverless Framework projects use a `serverless.yml` file to configure and deploy apps. @@ -206,7 +204,7 @@ You can [learn how to export Slack environment variables](/getting-started#setti ::: -**3. Install Serverless Offline** +### 3. Install Serverless Offline To make local development a breeze, we'll use the `serverless-offline` module to emulate a deployed function. @@ -224,7 +222,7 @@ Congratulations, you've just prepared your Bolt app for AWS Lambda and Serverles Now that your app is configured to respond to an AWS Lambda function, we'll set up your environment to run the app locally. -**1. Start your local servers** +### 1. Start your local servers First, use the `serverless offline` command to start your app and listen to AWS Lambda function events: @@ -250,7 +248,7 @@ ngrok http 3000 ::: -**2. Update your Request URL** +### 2. Update your Request URL Next, visit your [Slack app's settings](https://api.slack.com/apps) to update your **Request URL** to use the ngrok web address. @@ -264,18 +262,21 @@ Second, select **Event Subscriptions** from the side and update the **Request UR ![Event Subscriptions page](/img/event-subscriptions-page.png "Event Subscriptions page") -**3. Test your Slack app** +### 3. Test your Slack app -Now you can test your Slack app by inviting your app to a channel then saying “hello” (lower-case). Just like in the [Getting Started guide](/getting-started, your app should respond back: +Now you can test your Slack app by inviting your app to a channel then saying “hello” (lower-case). Just like in the [Getting Started guide](/getting-started), your app should respond back: -> 👩‍💻 hello
+``` +> 👩‍💻 hello +``` + +``` > 🤖 Hey there @Jane! +``` If you don’t receive a response, check your **Request URL** and try again. -:::info - -**How does this work?** +:::info[How does this work?] The ngrok and Serverless commands are configured on the same port (default: 3000). When a Slack event is sent to your **Request URL**, it's received on your local machine by ngrok. The request is then forwarded to Serverless Offline, which emulates an AWS Lambda function event and triggers your Bolt app's receiver. 🛫🛬 Phew, what a trip! @@ -289,7 +290,7 @@ In the previous section of this tutorial, you ran your app locally and tested it You can use the Serverless Framework tools to provision, package, and deploy your app onto AWS Lambda. After your app is deployed, you'll need to update your app's request URL to say "hello" to your app. ✨ -**1. Deploy the app to AWS Lambda** +### 1. Deploy the app to AWS Lambda Now, deploy your app to AWS Lambda with the following command: @@ -304,7 +305,7 @@ serverless deploy After your app is deployed, you'll be given an **endpoint** which you'll use as your app's **Request URL**. The **endpoint** should end in `/slack/events`. Go ahead and copy this **endpoint** to use in the next section. -**2. Update your Slack app's settings** +### 2. Update your Slack app's settings Now we need to use your AWS Lambda **endpoint** as your **Request URL**, which is where Slack will send events and actions. With your endpoint copied, navigate to your [Slack app's configuration](https://api.slack.com/apps) to update your app's **Request URLs**. @@ -317,16 +318,21 @@ Second, select **Event Subscriptions** from the side and update the **Request UR ![Event Subscriptions page](/img/event-subscriptions-page.png "Event Subscriptions page") -**3. Test your Slack app** +### 3. Test your Slack app Your app is now deployed and Slack is updated, so let's try it out! Just like the [running the app locally](#run-the-app-locally) section, open a Slack channel that your app is in and say "hello". You app should once again respond with a greeting: -> 👩‍💻 hello
+``` +> 👩‍💻 hello +``` + +``` > 🤖 Hey there @Jane! +``` -**4. Deploy an update** +### 4. Deploy an update As you continue to build your Slack app, you'll need to deploy the updates. Let's get a feel for this by updating your app to respond to a "goodbye" message. diff --git a/docs/content/deployments/heroku.md b/docs/content/deployments/heroku.md index 7593fd2cc..b399f9f67 100644 --- a/docs/content/deployments/heroku.md +++ b/docs/content/deployments/heroku.md @@ -1,20 +1,17 @@ --- -title: Heroku Platform +title: Deploying to Heroku lang: en --- -# Deploying to Heroku +This guide will walk you through preparing and deploying a Slack app using Bolt for JavaScript and the [Heroku platform](https://heroku.com/). Along the way, we’ll download a Bolt Slack app, prepare it for Heroku, and deploy it. + +When you’re finished, you’ll have this ⚡️[Deploying to Heroku app](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-heroku) to run, modify, and make your own. :::warning Using Heroku dynos to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy) as soon as you are done to control costs. - ::: - -This guide will walk you through preparing and deploying a Slack app using Bolt for JavaScript and the [Heroku platform](https://heroku.com/). Along the way, we’ll download a Bolt Slack app, prepare it for Heroku, and deploy it. - - -When you’re finished, you’ll have this ⚡️[Deploying to Heroku app](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-heroku) to run, modify, and make your own. +::: --- @@ -40,7 +37,7 @@ Now that you have an app, let's prepare it for Heroku. Heroku is a flexible platform that requires some configuration to host your app. In this section, we'll update your Bolt app to support Heroku. -**1. Use a Git repository** +### 1. Use a Git repository :::info @@ -50,7 +47,7 @@ Skip this step if you used `git clone` in the previous section because you alrea Before you can deploy your app to Heroku, you'll need a Git repository. If you aren't already using Git, you'll need to [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [create a Git repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository). -**2. Add a `Procfile`** +### Add a `Procfile` Every Heroku app uses a special file called `Procfile` that tells Heroku how to start your app. The contents of the file will depend on whether or not you are using Socket Mode. @@ -87,7 +84,7 @@ Are you following this guide with an existing Bolt app? If so, please review the Now we can set up the Heroku tools on your local machine. These tools will help you manage, deploy, and debug your app on Heroku's platform. -**1. Install the Heroku CLI** +### 1. Install the Heroku CLI The Heroku tools are available as a Command Line Interface (CLI). Go ahead and [install the Heroku CLI for macOS, Windows, or Linux](https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up). On macOS, you can run the command: @@ -107,7 +104,7 @@ If the `heroku` command is not found, refresh your path by opening a new termina ::: -**2. Log into the Heroku CLI** +### 2. Log into the Heroku CLI The Heroku CLI connects your local machine with your Heroku account. [Sign up for a free Heroku account](https://heroku.com) and then log into the Heroku CLI with the following command: @@ -120,7 +117,7 @@ If you're behind a firewall, you may need to [set the proxy environment variable ::: -**3. Confirm you're logged into the Heroku CLI** +### 3. Confirm you're logged into the Heroku CLI Check that you're logged in by displaying the account currently connected to your Heroku CLI: @@ -144,7 +141,7 @@ Eligible students can apply for platform credits through the [Heroku for GitHub ::: -**1. Create an app on Heroku** +### 1. Create an app on Heroku Create an app on Heroku with a unique name: @@ -172,7 +169,7 @@ After your app is created, you'll be given some information that we'll use in th - Web address is `https://sharp-rain-871.herokuapp.com/` - Empty Git remote is `https://git.heroku.com/sharp-rain-871.git` -**2. Confirm Heroku Git remote** +### 2. Confirm Heroku Git remote The Heroku CLI automatically adds a Git remote called `heroku` to your local repository. You can list your Git remotes to confirm `heroku` exists: @@ -182,7 +179,7 @@ git remote -v # heroku https://git.heroku.com/sharp-rain-871.git (push) ``` -**3. Set environment variables on Heroku** +### 3. Set environment variables on Heroku Now you'll need to add your Slack app credentials to your Heroku app: @@ -205,7 +202,7 @@ Now that we have prepared your local app and created a Heroku app, the next step To deploy the app, we're going to push your local code to Heroku, update your Slack app's settings, and say "hello" to your Heroku app. ✨ -**1. Deploy the app to Heroku** +### 1. Deploy the app to Heroku When deploying an app to Heroku, you'll typically use the `git push` command. This will push your code from your local repository to your `heroku` remote repository. @@ -227,7 +224,7 @@ Finally, we need to start a web server instance using the Heroku CLI: heroku ps:scale web=1 ``` -**2. Update your Slack app's settings** +### 2. Update your Slack app's settings Now we need to use your Heroku web address as your **Request URL**, which is where Slack will send events and actions. @@ -263,7 +260,7 @@ Heroku Eco Dyno apps sleep when inactive. 💤 If your verification fails, pleas ::: -**3. Test your Slack app** +### 3. Test your Slack app Your app is now deployed and Slack is updated, so let's try it out! diff --git a/docs/content/getting-started.mdx b/docs/content/getting-started.mdx index af9bfa0a7..e07b47c33 100644 --- a/docs/content/getting-started.mdx +++ b/docs/content/getting-started.mdx @@ -141,18 +141,18 @@ import TabItem from '@theme/TabItem'; -1. Head to your app's configuration page (click on the app [from your app management page](https://api.slack.com/apps)). Navigate to **Socket Mode** on the left side menu and toggle to enable. +1. Head to your app's configuration page (click on the app [from your app settings page](https://api.slack.com/apps)). Navigate to **Socket Mode** on the left side menu and toggle to enable. 2. Go to **Basic Information** and scroll down under the App Token section and click **Generate Token and Scopes** to generate an app token. Add the `connections:write` scope to this token and save the generated `xapp` token, we'll use that in just a moment. -Finally, it's time to tell Slack what events we'd like to listen for. Under **Event Subscriptions**, toggle the switch labeled **Enable Events**. +3. Finally, it's time to tell Slack what events we'd like to listen for. Under **Event Subscriptions**, toggle the switch labeled **Enable Events**. When an event occurs, Slack will send your app information about the event, like the user that triggered it and the channel it occurred in. Your app will process the details and can respond accordingly. -1. Go back to your app configuration page (click on the app from your [app management page](https://api.slack.com/apps)). Click **Event Subscriptions** on the left sidebar. Toggle the switch labeled **Enable Events**. +1. Go back to your app configuration page (click on the app from your [app settings page](https://api.slack.com/apps)). Click **Event Subscriptions** on the left sidebar. Toggle the switch labeled **Enable Events**. 2. Add your Request URL. Slack will send HTTP POST requests corresponding to events to this [Request URL](https://api.slack.com/apis/connections/events-api#the-events-api__subscribing-to-event-types__events-api-request-urls) endpoint. Bolt uses the `/slack/events` path to listen to all incoming requests (whether shortcuts, events, or interactivity payloads). When configuring your Request URL within your app configuration, you'll append `/slack/events`, e.g. `https:///slack/events`. 💡 @@ -162,7 +162,6 @@ For local development, you can use a proxy service like [ngrok](https://ngrok.co ::: - diff --git a/docs/content/legacy/conversation-store.md b/docs/content/legacy/conversation-store.md index 6c67bdb25..3a260fd53 100644 --- a/docs/content/legacy/conversation-store.md +++ b/docs/content/legacy/conversation-store.md @@ -4,7 +4,9 @@ lang: en slug: /concepts/conversation-store --- -Bolt for JavaScript includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods: +Bolt for JavaScript includes support for a store, which sets and retrieves state related to a conversation. + +Conversation stores have two methods: * `set()` modifies conversation state. `set()` requires a `conversationId` of type string, `value` of any type, and an optional `expiresAt` of type number. `set()` returns a `Promise`. * `get()` fetches conversation state from the store. `get()` requires a `conversationId` of type string and returns a Promise with the conversation’s state. diff --git a/docs/content/legacy/hubot-migration.md b/docs/content/legacy/hubot-migration.md index 2aa2a1c33..d29c40ad6 100644 --- a/docs/content/legacy/hubot-migration.md +++ b/docs/content/legacy/hubot-migration.md @@ -1,5 +1,6 @@ --- title: Migrating apps from Hubot to Bolt for JavaScript +sidebar_label: Hubot app migration slug: /tutorial/hubot-migration lang: en --- @@ -10,7 +11,7 @@ If you already have an [app with a bot user](https://api.slack.com/bot-users#get --- -### Setting the stage {#setting-the-stage} +## Setting the stage {#setting-the-stage} When translating a Hubot app to Bolt for JavaScript, it’s good to know how each are working behind the scenes. Slack’s Hubot adapter is built to interface with the [RTM API](https://api.slack.com/rtm), which uses a WebSocket-based connection that sends a stream of workspace events to your Hubot app. The RTM API is not recommended for most use cases since it doesn’t include support for newer platform features and it can become very resource-intensive, particularly if the app is installed on multiple or large Slack teams. The default Bolt for JavaScript receiver is built to support the [Events API](https://api.slack.com/events-api), which uses HTTP-based event subscriptions to send JSON payloads to your Bolt app. The Events API includes newer events that aren’t on RTM and is more granular and scalable. It’s recommended for most use cases, though one reason your app may be stuck using the RTM API could be that the server you’re hosting your app from has a firewall that only allows outgoing requests and not incoming ones. @@ -20,12 +21,10 @@ There are a few other differences you may want to consider before creating a Bol - Bolt for JavaScript doesn’t have support for external scripts. If your Hubot app uses external scripts that are necessary to your app’s functionality or deployment, you probably want to stay with Hubot for now. If you aren’t sure whether your app has any external scripts, you can check the `external-scripts.json` file. As we continue to invest in Bolt for JavaScript, we are thinking about the future and how to make development and deployment of Slack apps easier. If there’s a valuable external script that your app uses, we’d love to hear what it is [in the dedicated GitHub issue](https://github.com/slackapi/bolt-js/issues/119). - Hubot apps are written in Coffeescript, which transpiles into JavaScript. We decided to write Bolt in Typescript to give access to rich type information. Bolt apps can be developed using Typescript or JavaScript. The [example script](https://github.com/slackapi/bolt-js/blob/master/examples/hubot-example/script.js) shows you how your Coffeescript may translate to JavaScript. If your app is more than a few simple scripts, it may be worth looking into projects like [Decaffeinate](https://github.com/decaffeinate/decaffeinate) to convert your CoffeeScript to JavaScript. ---- - -### Configuring your bot {#configuring-your-bot} -If you have access to an existing Slack app with a bot user, you can [jump ahead to the next section](#configure-what-your-bot-will-hear). If you aren’t sure, go to your [App Management page](https://api.slack.com/apps) and check whether your Hubot app is there. If it is, you can use the credentials from that app ([go ahead and skip to the next section](#configure-what-your-bot-will-hear)). Otherwise, we’ll walk you through creating a Slack app. +## Configuring your bot {#configuring-your-bot} +If you have access to an existing Slack app with a bot user, you can [jump ahead to the next section](#configure-what-your-bot-will-hear). If you aren’t sure, go to your [app settings page](https://api.slack.com/apps) and check whether your Hubot app is there. If it is, you can use the credentials from that app ([go ahead and skip to the next section](#configure-what-your-bot-will-hear)). Otherwise, we’ll walk you through creating a Slack app. -#### Create a Slack app +### Create a Slack app The first thing you’ll want to do is [create a Slack app](https://api.slack.com/apps/new). @@ -41,12 +40,12 @@ This page contains an overview of your app in addition to important credentials Look around, add an app icon and description, and then let’s start configuring your app 🔩 -#### Add a bot user +### Add a bot user On Slack, Hubot apps employ bot users which are designed to interact with users in conversation. To add a bot user to your new app, click **Bot Users** on the left sidebar and then **Add A Bot User**. Give it a display name and username, then click **Add Bot User**. There’s more information about what the different fields are [on our API site](https://api.slack.com/bot-users#creating-bot-user). -### Configure what your bot will hear {#configure-what-your-bot-will-hear} +## Configure what your bot will hear {#configure-what-your-bot-will-hear} The [Events API](https://api.slack.com/bot-users#app-mentions-response) is a bot's equivalent of eyes and ears. It gives a bot a way to react to posted messages, changes to channels, and other activities that happen in Slack. :::info @@ -55,7 +54,7 @@ Before you configure your bot’s events, you’ll need a public URL. If you’v ::: -#### Listening for messages +### Listening for messages All Hubot apps can listen to messages by default, so we need to configure your bot user to do the same. After walking through [setting up events](/getting-started#setting-up-events), your Request URL should be verified. Scroll down to **Subscribe to Bot Events**. There are four events related to messages: `message.channels` (listens for messages in public channels), `message.groups` (listens for messages in private channels), `message.im` (listens for messages in the App Home/DM space), and `message.mpim` (listens for messages in multi-person DMs). @@ -64,7 +63,7 @@ If you only want your bot to listen to messages in channels, you can listen to ` After you’ve added the kinds of message events you want your bot to listen to, click **Save Changes**. -#### Listening for other events +### Listening for other events Your Hubot app may have responded to other events depending on what functionality you used. Look through your script and identify any places where your script uses `react`, `respond`, or `presenceChange`: - If your app uses `respond`, subscribe to the `app_mention` event. This listens for any time your bot user is mentioned. - If your app uses `react`, subscribe to the `reaction_added` event. This listens for any time a reaction is added to a message in channels your bot user is in. @@ -78,7 +77,7 @@ An added benefit to Bolt is you can listen to any [Events API event](https://api After you added events that correspond to your app’s functionality, click **Save Changes**. -### Changes to script interfaces {#changes-to-script-interfaces} +## Changes to script interfaces {#changes-to-script-interfaces} Bolt’s interface was designed to conform to the Slack API language as much as possible, while Hubot was designed with more generalized language to abstract multiple services. While the interfaces are similar, converting a Hubot script to a Bolt for JavaScript one still requires some code changes. Bolt for JavaScript doesn’t use `res` or expose the raw request from Slack. Instead, you can use the payload body from `payload`, or common functionality like sending a message using `say()`. @@ -89,14 +88,14 @@ To make it easier, we’ve created a sample script on GitHub that [showcases Hub ::: -#### Listening to patterns using `message()` +### Listening to patterns using `message()` Hubot scripts use `hear()` listen to messages with a matching pattern. Bolt for JavaScript instead uses `message()` and accepts a `string` or `RegExp` for the pattern. 👨‍💻👩‍💻 Anywhere where you use `hear()` in your code, change it to use `message()` [Read more about listening to messages](/concepts/message-listening). -#### Responding with a message using `say()` and `respond()` +### Responding with a message using `say()` and `respond()` Hubot scripts use `send()` to send a message to the same conversation and `reply()` to send a message to the same conversation with an @-mention to the user that sent the original message. Bolt for JavaScript uses `await say()` in place of `send()`, or `await respond()` to use the `response_url` to send a reply. To add an @-mention to the beginning of your reply, you can use the user ID found in the `context` object. For example, for a message event you could use `await say('<@${message.user}> Hello :wave:')` @@ -107,7 +106,7 @@ The arguments for Hubot’s `send()` and Bolt for JavaScript's `say()` are mostl [Read more about responding to messages](/concepts/message-sending). -#### `respond` and `react` +### `respond` and `react` In the previous section, you should have subscribed your app to the `app_mention` event if your Hubot script uses `respond()`, and `reaction_added` if you uses `react()`. @@ -117,7 +116,7 @@ Bolt for JavaScript uses a method called `event()` that allows you to listen to [Read more about listening to events](/concepts/event-listening). -### Using Web API methods with Bolt for JavaScript {#using-web-api-methods-with-bolt-for-javascript} +## Using Web API methods with Bolt for JavaScript {#using-web-api-methods-with-bolt-for-javascript} In Hubot, you needed to import the `WebClient` package from `@slack/client`. Bolt for JavaScript imports a `WebClient` instance for you by default, and exposes it as the `client` argument available on all listeners. To use the built-in `WebClient`, you’ll need to pass the token used to instantiate your app or the token associated with the team your request is coming from. This is found on the `context` object passed in to your listener functions. For example, to add a reaction to a message, you’d use: @@ -142,7 +141,7 @@ app.message('react', async ({ message, context, client, logger }) => { [Read more about using the Web API with Bolt](/concepts/web-api). -### Using middleware with Bolt for JavaScript {#using-middleware-with-bolt-for-javascript} +## Using middleware with Bolt for JavaScript {#using-middleware-with-bolt-for-javascript} Hubot has three kinds of middleware: receive (runs before any listeners are called), listener (runs for every matching listener), and response (runs for every response sent). Bolt for JavaScript only has two kinds of middleware — global and listener: @@ -155,7 +154,7 @@ To migrate your existing middleware functions, it’s evident that Hubot’s rec If your middleware needs to perform post-processing of an event, you can call `await next()` and any code after will be processed after the downstream middleware has been called. -### Migrating the brain to the conversation store {#migrating-the-brain-to-the-conversation-store} +## Migrating the brain to the conversation store {#migrating-the-brain-to-the-conversation-store} Hubot has an in-memory store called the brain. This enables a Hubot script to `get` and `set` basic pieces of data. Bolt for JavaScript uses a conversation store, which is a global middleware with a `get()`/`set()` interface. The default, built-in conversation store uses an in-memory store similar to Hubot, with the ability to set an expiration time in milliseconds. There are two ways to get and set conversation state: @@ -166,7 +165,7 @@ If there is more than one instance of your app running, the built-in conversatio [Read more about conversation stores](/concepts/conversation-store). -### Next steps {#next-steps} +## Next steps {#next-steps} If you’ve made it this far, it means you’ve likely converted your Hubot app into a Bolt for JavaScript app! ✨⚡ Now that you have your flashy new Bolt for JavaScript app, you can explore how to power it up: diff --git a/docs/content/legacy/steps-from-apps.md b/docs/content/legacy/steps-from-apps.md index 659786c2d..3d3803220 100644 --- a/docs/content/legacy/steps-from-apps.md +++ b/docs/content/legacy/steps-from-apps.md @@ -1,7 +1,7 @@ --- title: Steps from Apps lang: en -slug: /concepts/steps-from-apps +slug: /legacy/steps-from-apps --- :::danger diff --git a/docs/content/migration/migration-v2.md b/docs/content/migration/migration-v2.md index f7b5b2dff..f2737ce28 100644 --- a/docs/content/migration/migration-v2.md +++ b/docs/content/migration/migration-v2.md @@ -4,17 +4,15 @@ slug: /tutorial/migration-v2 lang: en --- -This guide will walk you through the process of updating your app from using `@slack/bolt@1.x` to `@slack/bolt@2.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes. - -:::info +End of life for `@slack/bolt@1.x` was **April 30th, 2021**. Development has been fully stopped for `@slack/bolt@1.x` and all remaining open issues and pull requests have been closed. -Make sure to checkout our [support schedule](#slackbolt1x-support-schedule) for `@slack/bolt@1.x` if you don't plan on upgrading right away* +This guide will walk you through the process of updating your app from using `@slack/bolt@1.x` to `@slack/bolt@2.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes. -::: +That being said, End of life for `@slack/bolt@2.x` was **May 31st, 2021**. After following this guide, you'll then want to follow the guide for [Migrating to V3](/tutorial/migration-v3). --- -### Upgrading your listeners to `async` {#upgrading-your-listeners-to-async} +## Upgrading your listeners to `async` {#upgrading-your-listeners-to-async} Listeners in your app should updated to `async` functions and `say()`, `respond()`, and `ack()` should be prefaced with `await`. @@ -36,8 +34,7 @@ app.action('some-action-id', async ({action, ack, say}) => { }) ``` - -### Error handling {#error-handling} +## Error handling {#error-handling} The recent changes in Bolt for JavaScript V2 have improved our ability to catch errors and filter them to the global error handler. It is still recommended to manage errors in the listeners themselves instead of letting them propagate to the global handler when possible. @@ -55,7 +52,7 @@ app.action('some-action-id', async ({action, ack, say, logger}) => { }) ``` -#### Handling errors with the global error handler +### Handling errors with the global error handler ```javascript app.error(async (error) => { @@ -69,8 +66,7 @@ Other error related changes include: - When your listener doesn’t call `ack` within the 3 second time limit, we log the failure instead of throwing an error. - If multiple errors occur when processing multiple listeners for a single event, Bolt for JavaScript will return a wrapper error with a `code` property of `ErrorCode.MultipleListenerError` and an `originals` property that contains an array of the individual errors. - -### Message shortcuts {#message-shortcuts} +## Message shortcuts {#message-shortcuts} [Message shortcuts](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (previously referred to as message actions) now use the `shortcut()` method instead of the `action()` method. @@ -92,7 +88,7 @@ app.shortcut('message-action-callback', async ({shortcut, ack, context}) => { }) ``` -### Upgrading middleware {#upgrading-middleware} +## Upgrading middleware {#upgrading-middleware} If you wrote a custom middleware, adjust your function to `async` and update `next()` to `await next()`. If your middleware does some post processing, instead of passing a function to `next()`, you can now run it after `await next()`. @@ -121,10 +117,6 @@ async function noBotMessages({ message, next }) { } ``` -### @slack/bolt@1.x support schedule {#slackbolt1x-support-schedule} - -`@slack/bolt@1.x` will be deprecated on **June 30th, 2020**. We plan on continuing to implement bug fixes and will also consider back-porting new features on a case by case basis up until then. Once `@slack/bolt@1.x` has been deprecated, we will only implement **critical bug fixes** until the official end of life date and close non critical issues and pull requests. End of life is slated for **April 30th, 2021**. At this time, development will fully stop for `@slack/bolt@1.x` and all remaining open issues and pull requests will be closed. - -### Minimum TypeScript version {#minimum-typescript-version} +## Minimum TypeScript version {#minimum-typescript-version} `@slack/bolt@2.x` requires a minimum TypeScript version of 3.7. diff --git a/docs/content/migration/migration-v3.md b/docs/content/migration/migration-v3.md index b453984a2..df46040db 100644 --- a/docs/content/migration/migration-v3.md +++ b/docs/content/migration/migration-v3.md @@ -4,17 +4,13 @@ slug: /tutorial/migration-v3 lang: en --- -This guide will walk you through the process of updating your app from using `@slack/bolt@2.x` to `@slack/bolt@3.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes. - -:::info - -Make sure to checkout our [support schedule](#slackbolt2x-support-schedule) for `@slack/bolt@2.x` if you don't plan on upgrading right away* +End of life for `@slack/bolt@2.x` was **May 31st, 2021**. Development has been fully stopped for `@slack/bolt@2.x` and all remaining open issues and pull requests have been closed. -::: +This guide will walk you through the process of updating your app from using `@slack/bolt@2.x` to `@slack/bolt@3.x`. There are a few changes you'll need to make but for most apps, these changes can be applied in 5 - 15 minutes. --- -### Org wide app installation changes to Installation Store & orgAuthorize {#org-wide-app-installation-changes-to-installationstore--orgauthorize} +## Org wide app installation changes to Installation Store & orgAuthorize {#org-wide-app-installation-changes-to-installationstore--orgauthorize} In [Bolt for JavaScript 2.5.0](https://github.com/slackapi/bolt-js/releases/tag/%40slack%2Fbolt%402.5.0), we introduced support for [org wide app installations](https://api.slack.com/enterprise/apps). To add support to your applications, two new methods were introduced to the Installation Store used during OAuth, `fetchOrgInstallation` & `storeOrgInstallation`. With `@slack/bolt@3.x`, we have dropped support for these two new methods for a simpler interface and to be better aligned with Bolt for Python and Bolt for Java. See the code samples below for the recommended changes to migrate. @@ -99,18 +95,14 @@ const authorizeFn = async ({ teamId, enterpriseId, isEnterpriseInstall}) => { } ``` -### HTTP Receiver as default {#http-receiver-as-default} +## HTTP Receiver as default {#http-receiver-as-default} In `@slack/bolt@3.x`, we have introduced a new default [`HTTPReceiver`](https://github.com/slackapi/bolt-js/issues/670) which replaces the previous default `ExpressReceiver`. This will allow Bolt for JavaScript apps to easily work with other popular web frameworks (Hapi.js, Koa, etc). `ExpressReceiver` is still being shipped with Bolt for JavaScript and `HTTPReceiver` will not provide all the same functionality. One use case that isn't supported by `HTTPReceiver` is creating custom routes (ex: create a route to do a health check). For these use cases, we recommend continuing to use `ExpressReceiver` by importing the class, and creating your own instance of it, and passing this instance into the constructor of `App`. See [our documentation on adding custom http routes](/concepts/custom-routes) for an example. -### @slack/bolt@2.x support schedule {#slackbolt2x-support-schedule} - -`@slack/bolt@2.x` will be deprecated on **January 12th, 2021**. We will only implement **critical bug fixes** until the official end of life date and close non critical issues and pull requests, which is slated for **May 31st, 2021**. At this time, development will fully stop for `@slack/bolt@2.x` and all remaining open issues and pull requests will be closed. - -### Minimum Node version {#minimum-node-version} +## Minimum Node version {#minimum-node-version} `@slack/bolt@3.x` requires a minimum Node version of `12.13.0` and minimum npm version of `6.12.0` . -### Minimum TypeScript version {#minimum-typescript-version} +## Minimum TypeScript version {#minimum-typescript-version} `@slack/bolt@3.x` requires a minimum TypeScript version of `4.1`. diff --git a/docs/content/migration/migration-v4.md b/docs/content/migration/migration-v4.md index cadc5233d..bf14b712c 100644 --- a/docs/content/migration/migration-v4.md +++ b/docs/content/migration/migration-v4.md @@ -26,13 +26,13 @@ This guide will walk you through the process of updating your app from using `@s - 🚳 [Steps From Apps related types, methods and constants were marked as deprecated](#sfa-deprecation). - 📦 [The `@slack/web-api` package leveraged within bolt-js is now exported under the `webApi` namespace](#web-api-export). -## Details +--- -### ⬆️ Minimum Node version {#minimum-node-version} +## ⬆️ Minimum Node version {#minimum-node-version} `@slack/bolt@4.x` requires a minimum Node version of `18` and minimum npm version of `8.6.0` . -### 🚥 Changes to middleware argument types {#middleware-arg-types} +## 🚥 Changes to middleware argument types {#middleware-arg-types} This change primarily applies to TypeScript users. @@ -52,21 +52,21 @@ type SomeMiddlewareArgs = { With the above, now when a message payload is wrapped in middleware arguments, it will contain an appropriate `message` property, whereas a non-message payload will be intersected with `unknown` - effectively a type "noop." No more e.g. `say: undefined` or `message: undefined` to deal with! -### 🌐 `@slack/web-api` v7 upgrade {#web-api-v7} +## 🌐 `@slack/web-api` v7 upgrade {#web-api-v7} All bolt handlers are [provided a convenience `client` argument](../concepts/web-api) that developers can use to make API requests to [Slack's public HTTP APIs][methods]. This `client` is powered by [the `@slack/web-api` package][web-api]. In bolt v4, `web-api` has been upgraded from v6 to v7. More APIs! Better argument type safety! And a whole slew of other changes, too. Many of these changes won't affect JavaScript application builders, but if you are building a bolt app using TypeScript, you may see some compilation issues. Head over to [the `@slack/web-api` v6 -> v7 migration guide](https://github.com/slackapi/node-slack-sdk/wiki/Migration-Guide-for-web%E2%80%90api-v7) to get the details on what changed and how to migrate to v7. -### 🔌 `@slack/socket-mode` v2 upgrade {#socket-mode-v2} +## 🔌 `@slack/socket-mode` v2 upgrade {#socket-mode-v2} While the breaking changes from this upgrade should be shielded from most bolt-js users, if you are using [the `SocketModeReceiver` or setting `socketMode: true`](../concepts/socket-mode) _and_ attach custom code to how the `SocketModeReceiver` operates, we suggest you read through [the `@slack/socket-mode` v1 -> v2 migration guide](https://github.com/slackapi/node-slack-sdk/wiki/Migration-Guide-for-socket%E2%80%90mode-2.0), just in case. -### 🚅 `express` v5 upgrade {#express-v5} +## 🚅 `express` v5 upgrade {#express-v5} For those building bolt-js apps using the `ExpressReceiver`, the packaged `express` version has been upgraded to v5. Best to check [the list of breaking changes in `express` v5](https://github.com/expressjs/express/blob/5.x/History.md#500--2024-09-10) and keep tabs on [express#5944](https://github.com/expressjs/express/issues/5944), which tracks the creation of an `express` v4 -> v5 migration guide. -### 🍽️ `@slack/types` exported as a named `types` export {#types-named-export} +## 🍽️ `@slack/types` exported as a named `types` export {#types-named-export} We are slowly moving more core Slack domain object types and interfaces into [the utility package `@slack/types`][types]. For example, recently we shuffled [Slack Events API payloads](https://api.slack.com/events) from bolt-js over to `@slack/types`. Similar moves will continue as we improve bolt-js. Ideally, we'd like for everyone - ourselves as Slack employees but of course you as well, dear developer - to leverage these types when modeling Slack domain objects. @@ -78,7 +78,7 @@ import { App, type types } from '@slack/bolt'; // Now you can get references to e.g. `types.BotMessageEvent` ``` -### 🧘 `SocketModeFunctions` class disassembled {#socketmodefunctions} +## 🧘 `SocketModeFunctions` class disassembled {#socketmodefunctions} If you previously imported the `SocketModeFunctions` class, you likely only did so to get a reference to the single static method available on this class: [`defaultProcessEventErrorHandler`](https://github.com/slackapi/bolt-js/blob/cd662ed540aa40b5cf20b4d5c21b0008db8ed427/src/receivers/SocketModeFunctions.ts#L13). Instead, you can now directly import the named `defaultProcessEventErrorHandler` export instead: @@ -92,7 +92,7 @@ SocketModeFunctions.defaultProcessEventErrorHandler import { defaultProcessEventHandler } from '@slack/bolt'; ``` -### 🏭 Built-in middleware changes {#built-in-middleware-changes} +## 🏭 Built-in middleware changes {#built-in-middleware-changes} Two [built-in middlewares](../reference#built-in-middleware-functions), `ignoreSelf` and `directMention`, previously needed to be invoked as a function in order to _return_ a middleware. These two built-in middlewares were not parameterized in the sense that they should just be used directly; as a result, you no longer should invoke them and instead pass them directly. @@ -112,7 +112,7 @@ app.message(directMention, async (args) => { }); ``` -### 🌩️ `AwsEvent` interface changes {#awsevent-changes} +## 🌩️ `AwsEvent` interface changes {#awsevent-changes} For users of the `AwsLambdaReceiver` and TypeScript, [we previously modeled, rather simplistically, the AWS event payloads](https://github.com/slackapi/bolt-js/blob/cd662ed540aa40b5cf20b4d5c21b0008db8ed427/src/receivers/AwsLambdaReceiver.ts#L11-L24): liberal use of `any` and in certain cases, incorrect property types altogether. We've now improved these to be more accurate and to take into account the two versions of API Gateway payloads that AWS supports (v1 and v2). Details for these changes are available in [#2277](https://github.com/slackapi/bolt-js/pull/2277). @@ -131,17 +131,17 @@ if ('path' in awsEvent) { this.logger.info(`No request handler matched the request: ${path}`); ``` -### 🧹 Removed deprecations {#removed-deprecations} +## 🧹 Removed deprecations {#removed-deprecations} - The deprecated type `KnownKeys` was removed. Admittedly, it wasn't very useful: `export type KnownKeys<_T> = never;` - The deprecated types `VerifyOptions` and `OptionsRequest` were removed. - The deprecated methods `extractRetryNum`, `extractRetryReason`, `defaultRenderHtmlForInstallPath`, `renderHtmlForInstallPath` and `verify` were removed. -### 🚳 Steps From Apps related deprecations {#sfa-deprecation} +## 🚳 Steps From Apps related deprecations {#sfa-deprecation} A variety of methods, constants and types related to Steps From Apps were deprecated and will be removed in bolt-js v5. -### 📦 `@slack/web-api` exported as `webApi` {#web-api-export} +## 📦 `@slack/web-api` exported as `webApi` {#web-api-export} To help application developers keep versions of various `@slack/*` dependencies in sync with those used by bolt-js, `@slack/web-api` is now exported from bolt-js under the `webApi` export. Unless applications have specific version needs from the `@slack/web-api` package, apps should be able to import `web-api` from bolt instead: diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 14963051a..da0f4d468 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -60,8 +60,9 @@ const config = { from: ['/tutorial/getting-started','/tutorial/getting-started-http'], }, { - to: '/concepts/steps-from-apps', + to: '/legacy/steps-from-apps', from: [ + '/concepts/steps', '/concepts/creating-steps', '/concepts/adding-editing-steps', '/concepts/saving-steps', diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/actions.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/actions.md index 510ac555f..756f88b42 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/actions.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/actions.md @@ -12,7 +12,11 @@ Bolt アプリは `action` メソッドを用いて、ボタンのクリック すべての `action()` の例で `ack()` が使用されていることに注目してください。Slack からリクエストを受信したことを確認するために、アクションリスナー内で `ack()` 関数を呼び出す必要があります。これについては、「[リクエストの確認](/concepts/acknowledge)」 セクションで説明しています。 -*注: Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。* +:::info + +Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。 + +::: `block_actions` ペイロードの詳細については、[こちら](https://api.slack.com/reference/interaction-payloads) をご覧ください。リスナー内からビューの完全なペイロードにアクセスするには、コールバック関数内で `body` 引数を参照します。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/authenticating-oauth.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/authenticating-oauth.md index f17fa03e7..25f06b8cb 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/authenticating-oauth.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/authenticating-oauth.md @@ -170,10 +170,7 @@ const app = new App({ }); ``` -
- -OAuth デフォルト設定をカスタマイズ - +## OAuth デフォルト設定をカスタマイズ `installerOptions` を使って OAuth モジュールのデフォルト設定を上書きすることができます。このカスタマイズされた設定は `App` の初期化時に渡します。以下の情報を変更可能です: @@ -237,5 +234,4 @@ const app = new App({ }, } }); -``` -
+``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/custom-routes.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/custom-routes.md index fbb559711..d42fb0420 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/custom-routes.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/custom-routes.md @@ -48,10 +48,7 @@ const app = new App({ })(); ``` -
- -カスタム ExpressReceiver ルート - +## カスタム ExpressReceiver ルート Bolt の組み込みの `ExpressReceiver` を使っているなら、カスタムの HTTP ルートを追加するのはとても簡単です。`v2.1.0` から `ExpressReceiver` には `router` というプロパティが追加されています。これは、さらにルートを追加できるように `App` 内部で保持している Express の [Router](http://expressjs.com/en/4x/api.html#router) を public にしたものです。 @@ -88,5 +85,4 @@ receiver.router.post('/secret-page', (req, res) => { await app.start(); console.log('⚡️ Bolt app started'); })(); -``` -
\ No newline at end of file +``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/error-handling.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/error-handling.md index 090c6795d..5d5159c4e 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/error-handling.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/error-handling.md @@ -54,10 +54,7 @@ app.error(async (error) => { }); ``` -
- -エラーハンドラーでのさらなるデータの参照 - +## エラーハンドラーでのさらなるデータの参照 グローバルエラーハンドラーの中で、リクエストからのデータをログ出力したい場合もあるでしょう。あるいは単に Bolt に設定した `logger` を利用したい場合もあるでしょう。 @@ -83,6 +80,4 @@ app.error(async ({ error, logger, context, body }) => { // デバッグのために teamId を使ってなんらかの処理 } }); -``` - -
+``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/global-middleware.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/global-middleware.md index 1e3189e7b..465964423 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/global-middleware.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/global-middleware.md @@ -10,7 +10,11 @@ slug: /concepts/global-middleware たとえば、アプリが、対応する内部認証サービス (SSO プロバイダ、LDAP など) で識別されたユーザーにのみ応答する必要があるとします。この場合、グローバルミドルウェアを使用して認証サービス内のユーザーレコードを検索し、ユーザーが見つからない場合はエラーとなるように定義するのがよいでしょう。 -*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。* +:::info + +Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。 + +::: ```javascript // Acme ID情報管理プロバイダ上のユーザからの着信リクエストと紐つけた認証ミドルウェア diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/listener-middleware.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/listener-middleware.md index 96d556b6b..74b90a494 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/listener-middleware.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/listener-middleware.md @@ -12,7 +12,11 @@ slug: /concepts/listener-middleware 例として、リスナーが人（ボットではないユーザー）からのメッセージのみを扱うケースを考えてみましょう。このためには、全てのボットメッセージを除外するリスナーミドルウェアを実装します。 -*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。* +:::info + +Bolt 2.x からミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](/tutorial/migration-v2)を参照してください。 + +::: ```javascript // 'bot_message' サブタイプを持つメッセージをフィルタリングするリスナーミドルウェア diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/logging.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/logging.md index c1307d5da..137c53cdd 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/logging.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/logging.md @@ -18,10 +18,7 @@ const app = new App({ }); ``` -
- -コンソール以外へのログ出力の送信 - +## コンソール以外へのログ出力の送信 ログの送信先をコンソール以外に設定したり、よりロガーを細かくコントロールしたい場合は、カスタムロガーを実装します。カスタムロガーは、以下のメソッド (`Logger` インターフェイスに定義されているもの) を実装する必要があります。 @@ -56,6 +53,4 @@ const app = new App({ setName: (name) => { }, }, }); -``` - -
\ No newline at end of file +``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-listening.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-listening.md index b03033f37..907b5b52c 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-listening.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-listening.md @@ -6,7 +6,6 @@ slug: /concepts/message-listening [アプリが受信可能な](https://api.slack.com/messaging/retrieving#permissions)メッセージをリッスンするには、`message` 型でないイベントを除外する `message()` メソッドを使用します。`message()` リスナーは `event('message')` と等価の機能を提供します。 - `message()` は、`string` 型か `RegExp` 型の、指定パターンに一致しないメッセージを除外する `pattern` パラメーター（指定は必須ではありません）を受け付けます。 ```javascript @@ -39,7 +38,6 @@ app.message(/^(hi|hello|hey).*/, async ({ context, say }) => { ## メッセージのサブタイプのフィルタリング - イベントのサブタイプをフィルタリングしたい場合、組み込みの `subtype()` ミドルウェアを使用できます。 `message_changed` や `message_replied` のような一般的なメッセージサブタイプの情報は、[メッセージイベントのドキュメント](https://api.slack.com/events/message#message_subtypes)を参照してください。 ```javascript diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-sending.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-sending.md index 5ccef4f28..a4b17b889 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-sending.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/message-sending.md @@ -15,10 +15,7 @@ app.message('knock knock', async ({ message, say }) => { }); ``` -
- -ブロックを用いたメッセージの送信 - +## ブロックを用いたメッセージの送信 `say()` は、より複雑なメッセージペイロードを受け付けるので、メッセージに機能やリッチな構造を与えることが容易です。 @@ -48,5 +45,4 @@ app.event('reaction_added', async ({ event, say }) => { }); } }); -``` -
\ No newline at end of file +``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/shortcuts.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/shortcuts.md index c440feb28..61a1bb6b7 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/shortcuts.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/shortcuts.md @@ -68,64 +68,57 @@ app.shortcut('open_modal', async ({ shortcut, ack, context, logger }) => { }); ``` -
- - 制約付きオブジェクトを使用したショートカットのリスニング - +## 制約付きオブジェクトを使用したショートカットのリスニング - 制約付きオブジェクトを使って `callback_id` や `type` によるリスニングができます。オブジェクト内の制約は文字列型または RegExp オブジェクトを使用できます。 +制約付きオブジェクトを使って `callback_id` や `type` によるリスニングができます。オブジェクト内の制約は文字列型または RegExp オブジェクトを使用できます。 - - - ```javascript - // callback_id が 'open_modal' と一致し type が 'message_action' と一致する場合のみミドルウェアが呼び出される - app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, context, client, logger }) => { - try { - // ショートカットリクエストの確認 - await ack(); +```javascript +// callback_id が 'open_modal' と一致し type が 'message_action' と一致する場合のみミドルウェアが呼び出される +app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, context, client, logger }) => { + try { + // ショートカットリクエストの確認 + await ack(); - // 組み込みの WebClient を使って views.open API メソッドを呼び出す - const result = await app.client.views.open({ - // `context` オブジェクトに保持されたトークンを使用 - token: context.botToken, - trigger_id: shortcut.trigger_id, - view: { - type: "modal", - title: { - type: "plain_text", - text: "My App" - }, - close: { - type: "plain_text", - text: "Close" + // 組み込みの WebClient を使って views.open API メソッドを呼び出す + const result = await app.client.views.open({ + // `context` オブジェクトに保持されたトークンを使用 + token: context.botToken, + trigger_id: shortcut.trigger_id, + view: { + type: "modal", + title: { + type: "plain_text", + text: "My App" + }, + close: { + type: "plain_text", + text: "Close" + }, + blocks: [ + { + type: "section", + text: { + type: "mrkdwn", + text: "About the simplest modal you could conceive of :smile:\n\nMaybe or ." + } }, - blocks: [ - { - type: "section", - text: { + { + type: "context", + elements: [ + { type: "mrkdwn", - text: "About the simplest modal you could conceive of :smile:\n\nMaybe or ." + text: "Psssst this modal was designed using " } - }, - { - type: "context", - elements: [ - { - type: "mrkdwn", - text: "Psssst this modal was designed using " - } - ] - } - ] - } - }); - - logger.info(result); - } - catch (error) { - logger.error(error); - } - }); - ``` + ] + } + ] + } + }); -
\ No newline at end of file + logger.info(result); + } + catch (error) { + logger.error(error); + } +}); +``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/socket-mode.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/socket-mode.md index 275cdea5c..b765a8e5b 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/socket-mode.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/socket-mode.md @@ -23,10 +23,7 @@ const app = new App({ })(); ``` -
- -ソケットモードレシーバーのカスタム初期化 - +## ソケットモードレシーバーのカスタム初期化 以下のように `@slack/bolt` から `SocketModeReceiver` を import して、カスタムされたインスタンスとして定義することができます。 @@ -53,6 +50,4 @@ const app = new App({ await app.start(); console.log('⚡️ Bolt app started'); })(); -``` - -
+``` \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md index 17c5a8c63..3d37bd4f8 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md @@ -6,13 +6,13 @@ slug: /concepts/updating-pushing-views モーダルでは、複数のモーダルをスタックのように積み重ねて表示できます。[`views.open`](https://api.slack.com/methods/views.open) という API を呼び出すと、まず親の（最初の）モーダルが表示されます。この最初の呼び出しの後、[`views.update`](https://api.slack.com/methods/views.update) を実行することでそのビューを書き換えることもできますし、最初に述べたように [`views.push`](https://api.slack.com/methods/views.push) で新しいモーダルを積み重ねて表示することもできます。 -**`views.update`** +## `views.update` モーダルの更新には、組み込みの API クライアントを使って `views.update` を呼び出します。この API 呼び出しには、そのモーダルを開いたときに生成された `view_id` と、更新後の内容を表現する `blocks` の配列を含む新しい `view` を渡します。ユーザーが既存のモーダル内の要素とインタラクションを行なった（例：ボタンを押す、メニューから選択する）ことをトリガーにビューを更新する場合、そのリクエストの `body` に `view_id` が含まれます。 -**`views.push`** +## `views.push` -モーダルのスタックに新しいモーダルを積み重ねるためには、組み込みの API クライアントを用いて `views.push` を呼び出します。この API 呼び出しには、有効な `trigger_id` と、新しく生成する [ビュー部分のペイロード](https://api.slack.com/reference/block-kit/views)を渡します。`views.push` の引数は モーダルを開始するときと同様です。最初のモーダルを開いた後、その上にさらに二つまで追加のモーダルをスタックに積み重ねることができます。 +モーダルのスタックに新しいモーダルを積み重ねるためには、組み込みの API クライアントを用いて `views.push` を呼び出します。この API 呼び出しには、有効な `trigger_id` と、新しく生成する [ビュー部分のペイロード](https://api.slack.com/reference/block-kit/views)を渡します。`views.push` の引数は [モーダルを開始するとき](/concepts/creating-modals)と同様です。最初のモーダルを開いた後、その上にさらに二つまで追加のモーダルをスタックに積み重ねることができます。 より詳細な情報は [API ドキュメント](/concepts/view-submissions)を参照してください。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/view-submissions.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/view-submissions.md index f22c6cf89..641de55d5 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/view-submissions.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/view-submissions.md @@ -14,7 +14,7 @@ slug: /concepts/view-submissions --- -##### モーダル送信でのビューの更新 +## モーダル送信でのビューの更新 `view_submission` リクエストに対してモーダルを更新するには、リクエストの確認の中で `update` という `response_action` と新しく作成した `view` を指定します。 @@ -33,7 +33,7 @@ app.view('modal-callback-id', async ({ ack, body }) => { --- -##### モーダルを閉じるときのハンドリング +## モーダルを閉じるときのハンドリング 💡 `view_closed` リクエストをリッスンするとき、`callback_id` と `type: 'view_closed'` を含むオブジェクトの指定が必要です。以下の例を参照してください。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/web-api.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/web-api.md index a5578871f..6eccc9c0b 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/web-api.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/web-api.md @@ -4,7 +4,7 @@ lang: ja-jp slug: /concepts/web-api --- -[Web API メソッド](https://api.slack.com/methods)を呼び出すには、リスナー関数の引数に `client` として提供されている [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api) を使用します。このインスタンスが使用するトークンは、Bolt アプリの初期化時に指定されたもの もしくは Slack からのリクエストに対して [`authorize` 関数](/concepts/authorization)から返されたものが設定されます。組み込みの [OAuth サポート](/concepts/authenticating-oauth)は、この後者のケースをデフォルトでハンドリングします。 +[Web API メソッド](https://api.slack.com/methods)を呼び出すには、リスナー関数の引数に `client` として提供されている [`WebClient`](https://tools.slack.dev/node-slack-sdk/web-api) を使用します。このインスタンスが使用するトークンは、Bolt アプリの初期化時に指定されたもの **もしくは** Slack からのリクエストに対して [`authorize` 関数](/concepts/authorization)から返されたものが設定されます。組み込みの [OAuth サポート](/concepts/authenticating-oauth)は、この後者のケースをデフォルトでハンドリングします。 Bolt アプリケーションは、トップレベルに `app.client` も持っています。このインスタンスには、トークンをメソッド呼び出しのパラメーターとして都度指定します。Slack からのリクエストが authorize されないユースケースや、リスナー関数の外で Web API を呼び出したい場合は、このトップレベルの `app.client` を使用します。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/aws-lambda.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/aws-lambda.md index 743589da5..5a266eb60 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/aws-lambda.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/aws-lambda.md @@ -3,16 +3,13 @@ title: AWS Lambda へのデプロイ lang: ja-jp --- -# AWS Lambda へのデプロイ - このガイドでは、Bolt for JavaScript、[Serverless Framework](https://serverless.com/)、[AWS Lambda](https://aws.amazon.com/lambda/) を使った Slack アプリの準備とデプロイの方法について説明します。 - この手順を全て終わらせたら、あなたはきっと⚡️ [Deploying to AWS Lambda](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-aws-lambda) のサンプルアプリを動作させたり、それに変更を加えたり、自分のアプリを作ったりすることができるようになるでしょう。 --- -### AWS Lambda のセットアップ {#set-up-aws-lambda} +## AWS Lambda のセットアップ {#set-up-aws-lambda} [AWS Lambda](https://aws.amazon.com/lambda/) はサーバーレスの Function-as-a-Service（FaaS）プラットフォームです。AWS Lambda を利用すると、サーバーを管理することなく、コードを実行することができます。このセクションでは、ローカルマシンから AWS Lambda にアクセスするための設定を行います。 @@ -22,7 +19,7 @@ lang: ja-jp ::: -**1. AWS アカウントを作成する** +### 1. AWS アカウントを作成する AWS アカウントをまだ持っていない場合は、[アカウントを作成](https://aws.amazon.com/)する必要があります。画面に表示される案内に沿って作成しましょう。 @@ -32,7 +29,7 @@ AWS アカウントをまだ持っていない場合は、[アカウントを作 ::: -**2. AWS のアクセスキーを作成する** +### 2. AWS のアクセスキーを作成する Lambda へのデプロイでは、プログラムから AWS アカウントにアクセスする手段が必要になります。AWS の世界では、このために**アクセスキー ID** と**シークレットアクセスキー**が必要です。 @@ -44,13 +41,13 @@ Lambda へのデプロイでは、プログラムから AWS アカウントに ::: -**3. AWS CLI をインストールする** +### 3. AWS CLI をインストールする AWS では [macOS、Windows、Linux](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) にインストールして利用できるコマンドラインインターフェイス（CLI）のツールが用意されています。 macOS では、[最新の .pkg インストーラーをダウンロード](https://awscli.amazonaws.com/AWSCLIV2.pkg)して AWS CLI をインストールできます。 -**4. AWS プロファイルを構成する** +### 4. AWS プロファイルを構成する AWS CLI を使ってプロファイルを構成します。プロファイルはローカルマシンに置かれ、アクセスキーのペアを保管します。この CLI やその他のツールは、このプロファイルを使って AWS にアクセスします。 @@ -74,12 +71,10 @@ aws configure --- -### Serverless Framework をセットアップする {#set-up-serverless-framework} +## Serverless Framework をセットアップする {#set-up-serverless-framework} [Serverless Framework](https://serverless.com/) では、AWS Lambda 向けのアプリの設定、デバッグ、デプロイを簡単に行うためのツールが用意されています。 -**1. Serverless Framework CLI をインストールする** - Serverless でも macOS、Windows、Linux にインストールして利用できるコマンドラインインターフェイス（CLI）のツールが用意されています。インストールするには Serverless の[入門ガイド（英語）](https://www.serverless.com/framework/docs/getting-started/) をお読みください。 インストールが完了したら Serverless CLI をテストするため、利用可能なコマンドを表示してみましょう。 @@ -92,7 +87,7 @@ Serverless のツールのセットアップが完了しました。次に、AWS --- -### Bolt Slack アプリを入手する {#get-a-bolt-slack-app} +## Bolt Slack アプリを入手する {#get-a-bolt-slack-app} まだ Bolt アプリを自分で作成したことがない場合は、[入門ガイド](/getting-started)を参照してください。テンプレートのアプリをクローンするには、以下のコマンドを実行します。 @@ -110,9 +105,9 @@ Bolt アプリを用意できました。次に AWS Lambda と Serverless Framew --- -### アプリをセットアップする {#prepare-the-app} +## アプリをセットアップする {#prepare-the-app} -**1. アプリを AWS Lambda に対応させる** +### 1. アプリを AWS Lambda に対応させる デフォルトでは、入門ガイドの Bolt サンプルアプリはソケットモードを使用しています。WebSocket イベントの代わりに HTTP リクエストをリッスンするため、 `app.js` の設定を変更しましょう。 @@ -174,7 +169,7 @@ module.exports.handler = async (event, context, callback) => { 完成したアプリのソースコードは、⚡️[deploy-aws-lambda](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-aws-lambda/app.js) のサンプルのようになります。 -**2. serverless.yml を追加する** +### 2. serverless.yml を追加する Serverless Framework のプロジェクトでは、アプリの設定とデプロイに `serverless.yml` ファイルを使用します。 @@ -206,7 +201,7 @@ plugins: ::: -**3. serverless-offline モジュールをインストールする** +### 3. serverless-offline モジュールをインストールする ローカルでの開発を容易にするため、`serverless-offline` モジュールを使ってデプロイ対象の関数をエミュレートできるようにしましょう。 @@ -220,11 +215,11 @@ npm install --save-dev serverless-offline --- -### アプリをローカルで実行する {#run-the-app-locally} +## アプリをローカルで実行する {#run-the-app-locally} アプリを AWS Lambda 関数に応答させるための準備が完了したので、次にローカルでアプリを実行できるように環境を設定します。 -**1. ローカルのサーバーを起動する** +### 1. ローカルのサーバーを起動する まず、アプリの起動と AWS Lambda 関数のイベントをリッスンするため、`serverless offline` コマンドを実行します。 @@ -250,7 +245,7 @@ ngrok http 3000 ::: -**2. リクエスト URL を変更する** +### 2. リクエスト URL を変更する 次に、[Slack アプリの設定](https://api.slack.com/apps)を開き、**リクエスト URL** を ngrok のウェブアドレスに変更します。 @@ -268,7 +263,7 @@ ngrok http 3000 ![「Event Subscriptions」ページ](/img/event-subscriptions-page.png "「Event Subscriptions」ページ") -**3. Slack アプリをテストする** +### 3. Slack アプリをテストする Slack アプリをテストします。今作った Bolt アプリを Slack のチャンネルに招待し、半角の小文字で「hello」と入力してみましょう。[入門ガイド](/getting-started)のとおり、アプリから応答があるはずです。 @@ -285,13 +280,13 @@ Slack アプリをテストします。今作った Bolt アプリを Slack の --- -### アプリをデプロイする {#deploy-the-app} +## アプリをデプロイする {#deploy-the-app} 今までローカルでアプリを実行し、 Slack ワークスペースでテストをしてきました。さて、動作するアプリができたので、デプロイしてみましょう! AWS Lambda 向けのアプリのプロビジョニング、パッケージング、デプロイには、Serverless Framework のツールが利用できます。アプリのデプロイが完了したら、アプリのリクエスト URL を更新して、「hello」と入力した時にアプリが応答できるようにします。✨ -**1. AWS Lambda にアプリをデプロイする** +### 1. AWS Lambda にアプリをデプロイする 次のコマンドを使って AWS Lambda にアプリをデプロイします。 @@ -312,7 +307,7 @@ serverless deploy ::: -**2. Slack アプリの設定を更新する** +### 2. Slack アプリの設定を更新する Slack からのイベントやアクションの送信先となる**リクエスト URL** に、発行された AWS Lambda の**エンドポイント**を指定します。[Slack アプリの構成](https://api.slack.com/apps)を開き、先ほどコピーしたエンドポイントを**リクエスト URL** に貼りつけます。 @@ -324,7 +319,7 @@ Slack からのイベントやアクションの送信先となる**リクエス ![「Event Subscriptions」ページ](/img/event-subscriptions-page.png "「Event Subscriptions」ページ") -**3. Slack アプリをテストする** +### 3. Slack アプリをテストする アプリのデプロイと、Slack の設定の更新が完了しました。動作を試してみましょう。 @@ -333,7 +328,7 @@ Slack からのイベントやアクションの送信先となる**リクエス > 👩‍💻 hello
> 🤖 Hey there @Jane! -**4. 更新をデプロイする** +### 4. 更新をデプロイする Slack アプリの開発を継続していくなら、更新したアプリをデプロイする必要が出てくるでしょう。それをやってみるために、「goodbye」というメッセージに応答するようにアプリを変更してみましょう。 @@ -355,11 +350,15 @@ serverless deploy デプロイが完了したら、アプリを参加させた Slack チャンネルを開いて、半角の小文字で「goodbye」と入力してみましょう。Slack アプリに「See you later」と表示されるはずです。 -> ⛳️ 一つの関数に小さな変更を加える場合、その関数だけをデプロイするためにより高速な `serverless deploy function -f my-function` を実行することができます。より詳細なヘルプを見るには `serverless help deploy function` を実行してください。 +:::tip + +一つの関数に小さな変更を加える場合、その関数だけをデプロイするためにより高速な `serverless deploy function -f my-function` を実行することができます。より詳細なヘルプを見るには `serverless help deploy function` を実行してください。 + +::: --- -### 次のステップ {#next-steps} +## 次のステップ {#next-steps} ⚡️[AWS Lambda を使った最初の Bolt for JavaScript アプリ](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-aws-lambda)をデプロイできました。🚀 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/heroku.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/heroku.md index 8eacde210..715e0ecd4 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/heroku.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/deployments/heroku.md @@ -3,16 +3,13 @@ title: Heroku へのデプロイ lang: ja-jp --- -# Heroku へのデプロイ - このガイドでは、Bolt for JavaScriptと[Heroku プラットフォーム](https://heroku.com/)を使ってSlack アプリを用意して、デプロイするまでの手順を説明します。全体の流れとしては、Bolt Slack アプリをダウンロードし、Heroku 用の準備を済ませ、デプロイする流れになります。 - この手順を全て終わらせたら、あなたはきっと️⚡️[getting-started-with-heroku](https://github.com/slackapi/bolt-js/tree/main/examples/deploy-heroku)のサンプルアプリを動作させたり、それに変更を加えたり、自分のアプリを作ったりすることができるようになるでしょう。 --- -### Bolt Slack アプリを入手する {#get-a-bolt-slack-app} +## Bolt Slack アプリを入手する {#get-a-bolt-slack-app} Bolt アプリを作るのが初めてという場合は、まず[Bolt 入門ガイド](/getting-started)に沿って進めてみましょう。または、以下のテンプレートアプリをクローンしてもよいでしょう。 @@ -30,11 +27,11 @@ cd bolt-js-getting-started-app/ --- -### アプリをHeroku で動かすための準備する {#prepare-the-app-for-heroku} +## アプリをHeroku で動かすための準備する {#prepare-the-app-for-heroku} Heroku は、作ったアプリをホストできる柔軟性の高いプラットフォームで、少し設定が必要です。このセクションでは、Bolt アプリに変更を加え、Heroku に対応させます。 -**1. Git リポジトリを使用する** +### 1. Git リポジトリを使用する Heroku にアプリをデプロイするには、まずGit リポジトリが必要です。まだGit を使ったことがない場合は、[Git をインストール](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)し、[Git リポジトリを作成](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)します @@ -44,7 +41,7 @@ Heroku にアプリをデプロイするには、まずGit リポジトリが必 ::: -**2. Procfile を追加する** +### 2. Procfile を追加する Heroku アプリでは、必ず`Procfile`という専用のファイルが必要です。このファイルを使ってHeroku にアプリの起動方法を伝えます。Bolt Slack アプリは、公開されたWeb アドレスを持つWeb サーバーとして起動します。 @@ -77,11 +74,11 @@ git commit -m "Add Procfile" --- -### Heroku ツールをセットアップする {#set-up-the-heroku-tools} +## Heroku ツールをセットアップする {#set-up-the-heroku-tools} ローカルマシンでHeroku ツールのセットアップを行います。このツールは、Heroku プラットフォームを使用するアプリの管理、デプロイ、デバッグを行う場合に便利です。 -**1. Heroku CLI をインストールする** +### 1. Heroku CLI をインストールする Heroku ツールは、コマンドラインインターフェイス（CLI）の形で提供されています。さっそく[macOS、Windows、Linux 用のHeroku CLI](https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up)をインストールしましょう。macOS では次のコマンドを実行します。 @@ -101,7 +98,7 @@ heroku help ::: -**2. Heroku CLI にログインする** +### 2. Heroku CLI にログインする Heroku CLI では、ローカルマシンからHeroku アカウントに接続します。[無料のHeroku アカウントを新規登録](https://heroku.com)して、次のコマンドでHeroku CLI にログインします。 @@ -114,7 +111,7 @@ heroku login ::: -**3. Heroku CLI へのログインが成功したか確認する** +### 3. Heroku CLI へのログインが成功したか確認する ログインできたかどうか確認しましょう。次のコマンドを実行すると、Heroku CLI に現在接続されているアカウント名が表示されます。 @@ -126,7 +123,7 @@ heroku auth:whoami --- -### Heroku アプリを作成する {#create-an-app-on-heroku} +## Heroku アプリを作成する {#create-an-app-on-heroku} 先ほどインストールしたツールを使って、[Heroku アプリを作成](https://devcenter.heroku.com/articles/creating-apps)します。アプリを作成するときは、ユニークな名前を自分で指定するか、ランダムな名前を生成することができます。 @@ -136,7 +133,7 @@ heroku auth:whoami ::: -**1. Heroku アプリを作成する** +### 1. Heroku アプリを作成する ユニークな名前を指定してHeroku アプリを作成します。 @@ -158,7 +155,7 @@ Heroku アプリが作成されると、いくつかの情報が表示されま - Web アドレス: `https://sharp-rain-871.herokuapp.com/` - 空のリモートGit リポジトリ: `https://git.heroku.com/sharp-rain-871.git` -**2. Heroku のリモートGit リポジトリを確認する** +### 2. Heroku のリモートGit リポジトリを確認する Heroku CLI は、自動的に`heroku`という名前のリモートGit リポジトリをローカルに追加します。リモートGit リポジトリを一覧して、`heroku`が存在することを確認しましょう。 @@ -168,7 +165,7 @@ git remote -v # heroku https://git.heroku.com/sharp-rain-871.git (push) ``` -**3. アプリをデプロイする** +### 3. アプリをデプロイする Slack アプリの認証情報をHeroku アプリに設定します。 @@ -187,11 +184,11 @@ heroku config:set SLACK_BOT_TOKEN=xoxb- --- -### アプリをデプロイする {#deploy-the-app} +## アプリをデプロイする {#deploy-the-app} アプリをデプロイするため、ローカルのコードをHeroku にプッシュします。その後Slack アプリの設定を更新し、Heroku アプリに"hello" と声をかけてみましょう。 ✨ -**1. Heroku にアプリをデプロイする** +### 1. Heroku にアプリをデプロイする Heroku へのアプリのデプロイには、通常`git push`コマンドを使用します。これにより、ローカルリポジトリのコードがリモートの`heroku`リポジトリにプッシュされます。 @@ -214,7 +211,7 @@ Heroku deploys code that's pushed to the [master or main branches](https://devce heroku ps:scale web=1 ``` -**2. Slack アプリの設定を更新する** +### 2. Slack アプリの設定を更新する 次に、Heroku のWeb アドレスをリクエストURL に指定し、Slack からのイベントやアクションがこのURL に送信されるようにします。 @@ -250,7 +247,7 @@ heroku info ::: -**3. Slack アプリをテストする** +### 3. Slack アプリをテストする アプリのデプロイが完了し、Slack の設定変更も行いました。アプリを試してみましょう。 @@ -258,7 +255,7 @@ heroku info --- -### 変更をデプロイする {#deploy-an-update} +## 変更をデプロイする {#deploy-an-update} Slack アプリを構築するなかで、変更を加えてデプロイする必要があります。一般的な流れでは、変更を加え、コミットし、Heroku にプッシュするという順番です。 @@ -288,7 +285,7 @@ git push heroku main --- -### 次のステップ {#next-steps} +## 次のステップ {#next-steps} これではじめて️⚡Bolt for JavaScript アプリをHerokuへデプロイすることに成功しました。🚀 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/getting-started.mdx b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/getting-started.mdx index ccee79ded..86c59dc29 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/getting-started.mdx +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/getting-started.mdx @@ -5,15 +5,13 @@ slug: getting-started lang: ja-jp --- -# Bolt 入門ガイド - このガイドでは、Bolt を使用して Slack アプリを起動し実行する方法について説明します。その過程で、新しい Slack アプリを作成し、ローカル環境を設定し、Slack ワークスペースからのメッセージをリッスンして応答するアプリを開発します。 このガイドが終わったら、あなたはこの⚡️[Getting Started app](https://github.com/slackapi/bolt-js-getting-started-app)を実行したり、修正したり、自分で作ったりすることができます。 --- -### アプリを作成する {#create-an-app} +## アプリを作成する {#create-an-app} 最初にやるべきこと: Bolt で開発を始める前に、 [Slack アプリを作成](https://api.slack.com/apps/new)します。 :::tip @@ -32,7 +30,7 @@ lang: ja-jp --- -### トークンとアプリのインストール {#tokens-and-installing-apps} +## トークンとアプリのインストール {#tokens-and-installing-apps} Slack アプリは、[OAuth を使用して、Slack の API へのアクセスを管理](https://api.slack.com/docs/oauth)します。アプリがインストールされるとトークンが発行されます。そのトークンを使って、アプリは API メソッドを呼び出すことができます。 Slack アプリで使用できるトークンには、ユーザートークン（`xoxp`）とボットトークン（`xoxb`）、アプリレベルトークン（`xapp`）の 3 種類があります。 @@ -60,7 +58,7 @@ Slack アプリで使用できるトークンには、ユーザートークン --- -### ローカルプロジェクトの設定 {#setting-up-your-project} +## ローカルプロジェクトの設定 {#setting-up-your-project} 初期設定が完了したので、次は新しい Bolt プロジェクトを設定します。ここで、アプリのロジックを処理するコードを記述します。 プロジェクトをまだ作成していない場合は、新しいプロジェクトを作成しましょう。次のように、空のディレクトリを作成して、新しいプロジェクトを初期化します。 @@ -128,7 +126,7 @@ node app.js --- -### イベントの設定 {#setting-up-events} +## イベントの設定 {#setting-up-events} アプリはワークスペース内の他のメンバーと同じように振る舞い、メッセージを投稿したり、絵文字リアクションを追加したり、イベントをリッスンして返答したりできます。 @@ -192,7 +190,7 @@ import TabItem from '@theme/TabItem'; --- -### メッセージのリスニングと応答 {#listening-and-responding-to-a-message} +## メッセージのリスニングと応答 {#listening-and-responding-to-a-message} これで、アプリでいくつかのロジックを設定する準備が整いました。まずは `message()` メソッドを使用して、メッセージのリスナーをアタッチしましょう。 次の例では、あなたのアプリが追加されているチャンネルや DM で `hello` という単語を含むすべてのメッセージをリッスンし、 `Hey there @user!` と応答します。 @@ -261,7 +259,7 @@ app.message('hello', async ({ message, say }) => { --- -### アクションの送信と応答 {#sending-and-responding-to-actions} +## アクションの送信と応答 {#sending-and-responding-to-actions} ボタン、選択メニュー、日付ピッカー、モーダルなどの機能を使用するには、インタラクティブ機能を有効にする必要があります。イベントと同様に、Slack の URL を指定してアクション ( 「ボタン・クリック」など) を送信する必要があります。 @@ -517,7 +515,7 @@ app.action('button_click', async ({ body, ack, say }) => { --- -### 次のステップ {#next-steps} +## 次のステップ {#next-steps} これで最初の Bolt アプリが構築できました! 🎉 基本的なアプリの作成ができましたので、次回は是非もっといろいろな、 Bolt の機能を使ってアプリを作ってみましょう。下記のリンクを辿っていろいろアイデアを模索してみてください！ @@ -526,4 +524,4 @@ app.action('button_click', async ({ body, ack, say }) => { * ボットが[`events()` メソッド](/concepts/event-listening)でリッスンできるさまざまなイベントを確認しましょう。イベントはすべて[API サイト](https://api.slack.com/events)にリストされています。 -* Bolt を使用すると、アプリにアタッチされているクライアントで [Web API メソッドを呼び出す](/concepts/web-api)ことができます。API サイトに [200 を超えるメソッド](https://api.slack.com/methods)を用意してあります。 +* Bolt を使用すると、アプリにアタッチされているクライアントで [Web API メソッドを呼び出す](/concepts/web-api)ことができます。API サイトに [200 を超えるメソッド](https://api.slack.com/methods)を用意してあります。 \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/hubot-migration.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/hubot-migration.md index 358171433..2be027651 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/hubot-migration.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/hubot-migration.md @@ -3,7 +3,6 @@ title: Hubot から Bolt に移行する方法 slug: hubot-migration lang: ja-jp --- -# Hubot のアプリを Bolt に移行する方法 Bolt は、Slack アプリを構築する時間と手間を減らすために作成されたフレームワークで、Slack 開発者のみなさんに最新機能とベストプラクティスを使用してアプリを構築できる単一のインターフェイスを提供します。このガイドでは、[Hubot で作成されたアプリを Bolt アプリに](https://hubot.github.com/docs/)移行するプロセスを順を追って説明します。 @@ -11,7 +10,7 @@ Bolt は、Slack アプリを構築する時間と手間を減らすために作 --- -### まずはじめに {#setting-the-stage} +## まずはじめに {#setting-the-stage} Hubot アプリを Bolt に変換するとき、それぞれが内部的にどのように機能しているかを把握しているとさらに理解を深めることができるでしょう。Slack の Hubot アダプターは、　WebSocket をベースとした [RTM API](https://api.slack.com/rtm) と接続するように実装されているので、Hubot アプリには一連のワークスペースイベントが一気にストリーミングされます。そして、RTM API は、新しいプラットフォーム機能をサポートしておらず、特にアプリが複数のまたは大規模な Slack チームにインストールされる場合には、膨大なリソースを消費する可能性があるため、ほとんどのユースケースでおすすめできません。 デフォルトの Bolt レシーバーは、[Events API](https://api.slack.com/events-api) をサポートするように構築されています。これは、HTTP ベースのイベントサブスクリプションを使用して Bolt アプリに JSON ペイロードを送信します。Events API には、RTM にはない新機能のイベントも含まれており、より細かい制御が可能でスケーラブルですのでほとんどのユースケースで推奨されています。しかし例外として、RTM API を使用し続けなければならない理由の 1 つに、アプリをホストしているサーバーにファイアウォールがあり、HTTP 送信リクエストのみを許可して、受信リクエストを許可しないというようなケースが挙げられます。 @@ -23,10 +22,10 @@ Bolt アプリを作成する前に考慮に入れた方がよい違いがほか --- -### ボットの設定 {#configuring-your-bot} -ボットユーザーを持つ既存の Slack アプリをお持ちの方は, 次のセクションに進むことができます。わからない場合は、[App Management ページ](https://api.slack.com/apps) に移動し、自分の Hubot アプリがあるかどうかを確認してください。ある場合は、そのアプリの認証情報をそのまま使用できます (次のセクションに進んでください)。ない場合は、下記の手順通りに進めていきましょう。 +## ボットの設定 {#configuring-your-bot} +ボットユーザーを持つ既存の Slack アプリをお持ちの方は, 次のセクションに進むことができます。わからない場合は、[app settings ページ](https://api.slack.com/apps) に移動し、自分の Hubot アプリがあるかどうかを確認してください。ある場合は、そのアプリの認証情報をそのまま使用できます (次のセクションに進んでください)。ない場合は、下記の手順通りに進めていきましょう。 -#### Slack アプリを作成する +## Slack アプリを作成する まず最初に、Slack アプリを作成します。 :::tip @@ -41,17 +40,21 @@ Bolt アプリを作成する前に考慮に入れた方がよい違いがほか ひと通り確認し、アプリのアイコンと説明を追加したら、アプリの構成 🔩 を始めましょう。 -#### ボットユーザーを追加する +### ボットユーザーを追加する Slack では、Hubot アプリはユーザーとの対話型のボットユーザーを採用しています。 新しいアプリにボットユーザーを追加するには、左側のサイドバーの **Bot Users** をクリックしてから、**Add A Bot User** をクリックします。表示名とユーザー名を指定して、**Add Bot User** をクリックします。その他のフィールドの詳しい情報は、[API サイト](https://api.slack.com/bot-users#creating-bot-user) をご覧ください。 -### ボットの設定 {#configure-what-your-bot-will-hear} +## ボットの設定 {#configure-what-your-bot-will-hear} [Events API](https://api.slack.com/bot-users#app-mentions-response) は、ボットの目と耳に相当します。これによりボットは、投稿されたメッセージ、チャンネルの変更、Slack で発生するその他のアクティビティに反応することができます。 -> ⚠️ボットのイベントを設定する前に、パブリック URL が必要です。Bolt アプリを作成したことがない場合、または Events API を使用したことがない場合は、『Getting Started ガイド』の [ローカル Bolt プロジェクトの設定](/getting-started) と [イベントの設定](/getting-started#setting-up-events) を参考にしてください。 +:::warning -#### メッセージのリスニング +ボットのイベントを設定する前に、パブリック URL が必要です。Bolt アプリを作成したことがない場合、または Events API を使用したことがない場合は、『Getting Started ガイド』の [ローカル Bolt プロジェクトの設定](/getting-started) と [イベントの設定](/getting-started#setting-up-events) を参考にしてください。 + +::: + +### メッセージのリスニング すべての Hubot アプリは、デフォルトでメッセージをリッスンできるので、ボットユーザーがそうするように設定する必要があります。 [イベントの設定](/getting-started#setting-up-events) を行ってから、リクエスト URL を入力、そして検証されたことを確認したら、**Subscribe to Bot Events** にスクロールダウンします。メッセージに関連する次の 4 つのイベントがあります `message channel` (パブリックチャンネルのメッセージをリッスン)、`message group` (プライベートチャンネルのメッセージをリッスン)、`message.im` (アプリのホーム/DM スペースのメッセージをリッスン)、`message.mpim` (マルチパーソン DM のメッセージをリッスン）。 @@ -60,7 +63,7 @@ Slack では、Hubot アプリはユーザーとの対話型のボットユー ボットにリッスンさせるメッセージイベントの種類を追加して、**Save Changes** をクリックします。 -#### その他のイベントのリッスン +### その他のイベントのリッスン 使用していた機能に応じて、Hubot アプリはほかのイベントにも応答していたかもしれません。スクリプトを調べて、`react`、`respond`、`presenceChange` が使用されている箇所を特定してください。 - アプリで `respond` が使用されている場合、`app_mention` イベントをサブスクライブします。これで、ボットユーザーがメンションされる時をリッスンします。 - アプリで `react` が使用されている場合、`reaction_added` イベントをサブスクライブします。これにより、ボットユーザーがいるチャンネルのメッセージにリアクションが追加される時をリッスンします。 @@ -74,41 +77,57 @@ Bolt に追加された利点として、どの [Events API イベント](https: アプリの機能に対応するイベントを追加 し終えたら、**Save Changes** をクリックします。 -### スクリプトインターフェイスの変更 {#changes-to-script-interfaces} +## スクリプトインターフェイスの変更 {#changes-to-script-interfaces} Bolt のインターフェイスは、可能な限り Slack API 言語に適合するように設計されましたが、Hubot は複数のサービスを抽象化するために一般化された言語を使用して設計されました。インターフェイスは似ていますが、Hubot スクリプトを Bolt スクリプトに変換するには、いくらかコードを変更する必要があります。 Bolt は、`res` を使用せず、Slack からの raw リクエストを公開しません。代わりに、`payload` 使ってペイロードボディを取得したり、`say()` を使ってメッセージを送信するといった一般的な機能を使用したりできます。 -> ⚙わかりやすくするために、サンプルスクリプトを Github 上に作成しました。このスクリプトは、[Bolt 用に書かれた機能と同等のものを使用している Hubot のコア機能を紹介しています。](https://github.com/slackapi/bolt-js/blob/master/examples/hubot-example/script.js) +:::tip + +⚙わかりやすくするために、サンプルスクリプトを Github 上に作成しました。このスクリプトは、[Bolt 用に書かれた機能と同等のものを使用している Hubot のコア機能を紹介しています。](https://github.com/slackapi/bolt-js/blob/master/examples/hubot-example/script.js) -#### `message()` を使用したパターンのリスニング +::: + +### `message()` を使用したパターンのリスニング Hubot スクリプトは、`hear()` を使用して、一致するパターンを持つメッセージをリッスンします。代わりに、 Bolt は `message()` を使用して、そのパターンの `string` または `RegExp` を受け入れます。 -> 👨‍💻👩‍💻コードで `hear()` を使用している箇所はすべて、`message()` を使用するように変更してください。 +:::tip + +👨‍💻👩‍💻コードで `hear()` を使用している箇所はすべて、`message()` を使用するように変更してください。 + +::: [メッセージのリスニングについてもっと詳しく読む](/concepts/message-listening). -#### `say()` および `respond()` を使用したメッセージで応答する +### `say()` および `respond()` を使用したメッセージで応答する Hubot スクリプトは、`send()` を使用してメッセージを同じ会話に送信し、`reply()` を使用して、元のメッセージを送信したユーザー宛の@メンションを付けて、メッセージを同じ会話上に送信します。 Bolt は、`send()` の代わりに `say()` を使用し、`respond()` を使用して `response_url` で返信を送信します。返信の冒頭にメンションを追加するには、`context` オブジェクトにあるユーザー ID を使用できます。たとえば、メッセージイベントの場合は次のようにできます: `say('<@${message.user}>Hello :wave:')` Hubot の `send()` と Bolt の `say()` はほとんど同じですが、`say()` を使用すると [ボタン、メニューの選択、デートピッカー](https://api.slack.com/messaging/interactivity#interaction) といったインタラクティブなコンポーネントを付けてメッセージを送信できます。 -> 👨‍💻👩‍💻コードで `send()` が使用されている箇所はすべて `say()` に変更してください +:::tip + +👨‍💻👩‍💻コードで `send()` が使用されている箇所はすべて `say()` に変更してください + +::: [メッセージへの応答についてもっと詳しく読む](/concepts/message-sending). -#### `respond` と `react` +### `respond` と `react` 前のセクションで、Hubot スクリプトで `respond()` が使用されている場合は `app_mention` イベントを、`react()` が使用されている場合は `reaction_added` をサブスクライブするようにアプリを設定しました。 Bolt は、`event()` と呼ばれるメソッドを使用して、任意の [Events API イベント](https://api.slack.com/events) をリッスンできます。コードを変更するには、`respond()` を app.event(‘app_mention’) に、`react()` を `app.event(‘reaction_added’)` に変更するだけです。この点は、[サンプルスクリプト](https://github.com/slackapi/bolt-js/blob/master/examples/hubot-example/script.js) で詳しく説明されています。 -> 👨‍💻👩‍💻コードで `respond()` が使用されている箇所はすべて、app.event ('app_mention') を使用するように変更してください。`react` が使用されている箇所はすべて `app.event('reaction_added')` に変更してください。 +:::tip + +👨‍💻👩‍💻コードで `respond()` が使用されている箇所はすべて、app.event ('app_mention') を使用するように変更してください。`react` が使用されている箇所はすべて `app.event('reaction_added')` に変更してください。 + +::: [イベントのリッスンについてもっと詳しく読む](/concepts/event-listening). -### Bolt で Web API メソッドを使用する {#using-web-api-methods-with-bolt-for-javascript} +## Bolt で Web API メソッドを使用する {#using-web-api-methods-with-bolt-for-javascript} Hubot では、`@slack/client` から `WebClient` パッケージをインポートする必要がありました。Bolt では、`app.client` からアクセスできる `WebClient` インスタンスがデフォルトでインポートされます。 組み込みの `WebClient` を使用するには、アプリをインスタンス化するために使用されるトークン、またはリクエストの送信元のチームに関連付けられているトークンを渡す必要があります。これは、リスナー関数に渡された `context` オブジェクトにあります。たとえば、メッセージにリアクションを追加するには、次を使用します: @@ -129,11 +148,15 @@ app.message('react', async ({ message, context, logger }) => { }); ``` -> 👨‍💻👩‍💻`app.client` で組み込みのクライアントを使用するように、Web API 呼び出しを変更してください。 +:::tip + +👨‍💻👩‍💻`app.client` で組み込みのクライアントを使用するように、Web API 呼び出しを変更してください。 + +::: [Bolt での Web API の使用についてもっと詳しく読む。](/concepts/web-api) -### Bolt でのミドルウェアの使用 {#using-middleware-with-bolt-for-javascript} +## Bolt でのミドルウェアの使用 {#using-middleware-with-bolt-for-javascript} Hubot には、受信 (リスナーが呼び出される前に実行される)、リスナー (一致するすべてのリスナーに対して実行される)、応答 (送信されるすべての応答に対して実行される) という 3 種類のミドルウェアがあります。 Bolt には、グローバルとリスナーという 2 種類のミドルウェアしかありません。 @@ -146,7 +169,7 @@ Bolt では、グローバルとリスナーというミドルウェアはいず ミドルウェアがイベントの後処理を実行する必要がある場合、`undefined` で呼び出すのではなく、後処理関数を使用して `await next()` を呼び出すことができます。後処理関数は、ミドルウェア関数が `await next()` を呼び出すのと同じ方法で` done()` を呼び出す必要があります(`Error` で呼び出すことも可能) 。 -### Brain を conversation store に移行する {#migrating-the-brain-to-the-conversation-store} +## Brain を conversation store に移行する {#migrating-the-brain-to-the-conversation-store} Hubot には、brain と呼ばれるメモリ内ストレージがあります。これによって、Hubot スクリプトはデータの基本部分を `get` および `set` することができます。Bolt は、conversation store と呼ばれる、`get()`/`set()` インターフェイスを含むグローバルミドルウェアを使用します。 デフォルトの組み込み conversation store は Hubot に似たメモリ内ストレージを使用し、ミリ秒単位で有効期限を設定できます。conversation の状態情報を get および set する方法は 2 つあります。 @@ -157,7 +180,7 @@ Hubot には、brain と呼ばれるメモリ内ストレージがあります [会話ストアについてもっと詳しく読む](/concepts/conversation-store). -### 次のステップ {#next-steps} +## 次のステップ {#next-steps} ここまで来れば、きっと Hubot アプリを Bolt アプリに変換できているはずです！✨⚡ 新しくなってよりクールになった Bolt アプリを、さらにパワーアップしていくこともできます。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/steps-from-apps.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/steps-from-apps.md index a131e4320..867785076 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/steps-from-apps.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/legacy/steps-from-apps.md @@ -1,7 +1,7 @@ --- title: ワークフローステップの概要 lang: ja-jp -slug: /concepts/steps-from-apps +slug: /legacy/steps-from-apps --- （アプリによる）ワークフローステップ（Workflow Steps from Apps) は、[ワークフロービルダー](https://api.slack.com/workflows)におけるワークフローに組み込み可能なカスタムのワークフローステップを任意の Slack アプリが提供することを可能とします。 diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v2.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v2.md index 1361e1f5a..e105b15ba 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v2.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v2.md @@ -4,15 +4,13 @@ slug: /tutorial/migration-v2 lang: ja-jp --- -# 2.x マイグレーションガイド +`@slack/bolt@1.x` End of life は **2021 年 4 月 30 日** の予定です。この日からは `@slack/bolt@1.x` の開発は完全に終了となり、残っている open issue や pull request もクローズされます。 このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。いくつかの変更が必要とはなりますが、ほとんどのアプリの場合で、おそらく対応に必要な時間は 5 〜 15 分程度です。 -*注: もしすぐにアップグレードをしない場合は、[Bolt 1.x に関するサポートスケジュール](#slackbolt1x-support-schedule)をご確認ください* - --- -### リスナー関数を `async` 関数に変更 {#upgrading-your-listeners-to-async} +## リスナー関数を `async` 関数に変更 {#upgrading-your-listeners-to-async} Bolt アプリ内のリスナー関数は、全て `async` 関数に変更する必要があります。そして、そのリスナー関数内の `say()`、`respond()`、`ack()` メソッドの呼び出しも全て `await` を呼び出しの前につける必要があります。 @@ -34,11 +32,11 @@ app.action('some-action-id', async ({action, ack, say}) => { }) ``` -### エラーハンドリング {#error-handling} +## エラーハンドリング {#error-handling} Bolt for JavaScript 2.x では、より多くのユースケースで、必要に応じてエラーをキャッチし、グローバルエラーハンドラーにそれを送るかを制御できるよう改善されました。これまでと同様、グローバルエラーハンドラーに全て任せるよりは、可能な限り、リスナー関数の内部でエラーに対処することをおすすめします。 -#### リスナー関数内で `try`/`catch` 節を用いたエラーハンドリング +### リスナー関数内で `try`/`catch` 節を用いたエラーハンドリング ```javascript app.action('some-action-id', async ({action, ack, say, logger}) => { @@ -52,7 +50,7 @@ app.action('some-action-id', async ({action, ack, say, logger}) => { }) ``` -#### グローバルエラーハンドラーによるエラーハンドリング +### グローバルエラーハンドラーによるエラーハンドリング ```javascript app.error(async (error) => { @@ -66,7 +64,7 @@ app.error(async (error) => { - リスナー関数が `ack()` メソッドを 3 秒間のうちに呼び出さなかった場合、これまでのように例外を投げるのではなくログを出力するようになりました - もし一つのイベントに対して複数のリスナー関数を実行中に複数のエラーが発生した場合、Bolt for JavaScript は `ErrorCode.MultipleListenerError` の値での `code` と、発生した個々のエラーの配列を含む `originals` というパラメーターをラップしたエラーを返します -### メッセージショートカット {#message-shortcuts} +## メッセージショートカット {#message-shortcuts} [メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (以前はメッセージアクションと呼ばれていました)は、これまで `action()` メソッドでハンドリングしていましたが `shortcut()` メソッドを使うようになりました。 @@ -88,7 +86,7 @@ app.shortcut('message-action-callback', async ({shortcut, ack, context}) => { }) ``` -### ミドルウェアに関する変更 {#upgrading-middleware} +## ミドルウェアに関する変更 {#upgrading-middleware} もしカスタムのミドルウェアを書いている場合は、その関数を `async` に変更し、さらに `next()` の呼び出しを `await next()` に変更してください。もし後続の処理がある場合は、関数を `next()` に渡す代わりに、その後続の処理を `await next()` の後に実行してください。 @@ -116,10 +114,6 @@ async function noBotMessages({message, next }) { } ``` -### Bolt 1.x のサポートスケジュール {#slackbolt1x-support-schedule} - -`@slack/bolt@1.x` は **2020 年 6 月 30 日** より非推奨となります。それまでの期間はケースバイケースでバグ修正や新機能のバックポートを対応を継続します。`@slack/bolt@1.x` が非推奨となった後は、End of life（正式サポートの終了日）まで **クリティカルなバグ修正のみ** を実装し、クリティカルではない issue や pull request はクローズします。End of life は **2021 年 4 月 30 日** の予定です。この日からは `@slack/bolt@1.x` の開発は完全に終了となり、残っている open issue や pull request もクローズされます。 - -### TypeScript の最低必須バージョン {#minimum-typescript-version} +## TypeScript の最低必須バージョン {#minimum-typescript-version} TypeScript 利用ガイド でも説明していますが、`@slack/bolt@2.x` は TypeScript 3.7 以上が必須バージョンです。 \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v3.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v3.md index cc795ed16..f644355d1 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v3.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/migration/migration-v3.md @@ -3,15 +3,14 @@ title: 3.x マイグレーションガイド slug: /tutorial/migration-v3 lang: ja-jp --- -# 3.x マイグレーションガイド -このガイドは Bolt 2.x を利用しているアプリを 3.x にアップグレードするための手順について説明します。いくつかの変更が必要とはなりますが、ほとんどのアプリの場合で、おそらく対応に必要な時間は 5 〜 15 分程度です。 +`@slack/bolt@2.x` End of life は **2021 年 5 月 31 日** の予定です。この日からは `@slack/bolt@2.x` の開発は完全に終了となり、残っている open issue や pull request もクローズされます。 -*注: もしすぐにアップグレードをしない場合は、[Bolt 2.x に関するサポートスケジュール](#slackbolt2x-support-schedule)をご確認ください* +このガイドは Bolt 2.x を利用しているアプリを 3.x にアップグレードするための手順について説明します。いくつかの変更が必要とはなりますが、ほとんどのアプリの場合で、おそらく対応に必要な時間は 5 〜 15 分程度です。 --- -### InstallationStore と orgAuthorize での OrG レベルでのインストール対応に関する変更 {#org-wide-app-installation-changes-to-installationstore--orgauthorize} +## InstallationStore と orgAuthorize での OrG レベルでのインストール対応に関する変更 {#org-wide-app-installation-changes-to-installationstore--orgauthorize} [Bolt for JavaScript 2.5.0](https://github.com/slackapi/bolt-js/releases/tag/%40slack%2Fbolt%402.5.0) で、私たちは [OrG レベルでのインストール](https://api.slack.com/enterprise/apps)のサポートを追加しました。このサポートをあなたのアプリケーションに追加するには、OAuth フローの中で使用される `fetchOrgInstallation`、`storeOrgInstallation` という二つの新しいメソッドを導入する必要がありました。 3.x では、よりシンプルなインタフェースの実現と Bolt for Python、Bolt for Java との互換性を考慮して、これらの二つの新しいメソッドのサポートを廃止しました。マイグレーションに必要となる変更については以下のコード例を参考にしてください。 @@ -93,18 +92,14 @@ const authorizeFn = async ({ teamId, enterpriseId, isEnterpriseInstall}) => { } ``` -### デフォルトのレシーバーを HTTPReceiver に変更 {#http-receiver-as-default} +## デフォルトのレシーバーを HTTPReceiver に変更 {#http-receiver-as-default} 3.x から新しい [`HTTPReceiver`](https://github.com/slackapi/bolt-js/issues/670) というレシーバーを導入し、デフォルトのレシーバー実装を、これまでの `ExpressReceiver` からこのレシーバーに変更します。この変更は、Bolt for JavaScript を Express.js 以外の人気のある Web フレームワーク（Hapi.js や Koa など）とともに動作させることを容易にします。`ExpressReceiver` は引き続き Bolt for JavaScript のリリースに含まれます。また、`HTTPReceiver` は `ExpressReceiver` が提供する全ての機能を提供するわけではありません。例えば、一つのユースケースとしては、`HTTPReceiver` ではカスタムの HTTP ルート（例: ヘルスチェックのための URL を追加する）を追加する機能はサポートされていません。このようなユースケースに対応するためには、引き続き `ExpressReceiver` を利用することを推奨します。その場合はクラスを import して、インスタンス化したものを `App` のコンストラクタに渡してください。詳細は[カスタム HTTP ルートの追加](/concepts/custom-routes)を参考にしてください。 -### Bolt 2.x のサポートスケジュール {#slackbolt2x-support-schedule} - -`@slack/bolt@2.x` は **2021 年 1 月 12 日** より非推奨となります。それまでの期間はケースバイケースでバグ修正や新機能のバックポートを対応を継続します。`@slack/bolt@2.x` が非推奨となった後は、End of life（正式サポートの終了日）まで **クリティカルなバグ修正のみ** を実装し、クリティカルではない issue や pull request はクローズします。End of life は **2021 年 5 月 31 日** の予定です。この日からは `@slack/bolt@2.x` の開発は完全に終了となり、残っている open issue や pull request もクローズされます。 - -### Node の最低必須バージョン {#minimum-node-version} +## Node の最低必須バージョン {#minimum-node-version} `@slack/bolt@3.x` は Node は `12.13.0` 以上、npm は `6.12.0` 以上が必須バージョンです。 -### TypeScript の最低必須バージョン {#minimum-typescript-version} +## TypeScript の最低必須バージョン {#minimum-typescript-version} TypeScript 利用ガイド でも説明していますが、`@slack/bolt@3.x` は TypeScript 4.1 以上が必須バージョンです。 \ No newline at end of file diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/reference.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/reference.md index ddf47a638..c0fbed56a 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/reference.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/reference.md @@ -1,11 +1,10 @@ --- -title: リファレンス +title: リファレンス（Appインターフェイスと設定） +sidebar_label: リファレンス slug: reference permalink: /reference --- -# リファレンス（Appインターフェイスと設定） - このガイドでは、Bolt インターフェイスのリスナー関数、リスナー関数の引数、初期化オプション、エラーについて詳しく説明します。⚡[入門ガイド](/getting-started)をまだ完了していない場合は、先にそちらで Bolt for JavaScript アプリ開発の基本を確認しておきましょう。 ## リスナー関数 {#listener-functions} @@ -108,7 +107,11 @@ App オプションは、`App` のコンストラクターに渡します。`rec | `deferInitialization` | アプリの初期化を遅延させる真偽値です。有効にすると非同期の `App#init()` メソッドを手動で呼び出す必要があります。 また `init()` メソッドは `App#start()` を実行する前に呼び出さなければなりません。 デフォルトは `false` です。 | | `signatureVerification` | Boltが着信リクエストでSlackの署名を検証する必要があるかどうかを決定するブール値。 デフォルトは`true`です。 | -> Bolt のclientは [Node Slack SDK](https://tools.slack.dev/node-slack-sdk) の `WebClient` のインスタンスです。そのため、Node Slack SDK のドキュメントも合わせて参照すると、開発時の理解に役立つでしょう。 +:::tip + +Bolt のclientは [Node Slack SDK](https://tools.slack.dev/node-slack-sdk) の `WebClient` のインスタンスです。そのため、Node Slack SDK のドキュメントも合わせて参照すると、開発時の理解に役立つでしょう。 + +::: ## フレームワークのエラー {#framework-error-types} From 186cdcffdf4c208063a8a504c69a1e9b05748724 Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Tue, 29 Oct 2024 17:58:51 -0700 Subject: [PATCH 2/3] docs: js specific title --- docs/docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index da0f4d468..cb77a227d 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -8,7 +8,7 @@ import { themes as prismThemes } from 'prism-react-renderer'; /** @type {import('@docusaurus/types').Config} */ const config = { - title: 'Slack Developer Tools', + title: 'Bolt for JavaScript', tagline: 'Official frameworks, libraries, and SDKs for Slack developers', favicon: 'img/favicon.ico', From c3666aa0039b3569891105fcbfa5b841eddbbf97 Mon Sep 17 00:00:00 2001 From: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com> Date: Tue, 29 Oct 2024 18:46:05 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Michael Brooks --- docs/content/migration/migration-v4.md | 2 +- .../current/concepts/updating-pushing-views.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/migration/migration-v4.md b/docs/content/migration/migration-v4.md index bf14b712c..94b799705 100644 --- a/docs/content/migration/migration-v4.md +++ b/docs/content/migration/migration-v4.md @@ -28,7 +28,7 @@ This guide will walk you through the process of updating your app from using `@s --- -## ⬆️ Minimum Node version {#minimum-node-version} +## ⬆️ Minimum Node version {#minimum-node-version} `@slack/bolt@4.x` requires a minimum Node version of `18` and minimum npm version of `8.6.0` . diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md index 3d37bd4f8..0f7d99804 100644 --- a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md +++ b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/concepts/updating-pushing-views.md @@ -10,7 +10,7 @@ slug: /concepts/updating-pushing-views モーダルの更新には、組み込みの API クライアントを使って `views.update` を呼び出します。この API 呼び出しには、そのモーダルを開いたときに生成された `view_id` と、更新後の内容を表現する `blocks` の配列を含む新しい `view` を渡します。ユーザーが既存のモーダル内の要素とインタラクションを行なった（例：ボタンを押す、メニューから選択する）ことをトリガーにビューを更新する場合、そのリクエストの `body` に `view_id` が含まれます。 -## `views.push` +## `views.push` モーダルのスタックに新しいモーダルを積み重ねるためには、組み込みの API クライアントを用いて `views.push` を呼び出します。この API 呼び出しには、有効な `trigger_id` と、新しく生成する [ビュー部分のペイロード](https://api.slack.com/reference/block-kit/views)を渡します。`views.push` の引数は [モーダルを開始するとき](/concepts/creating-modals)と同様です。最初のモーダルを開いた後、その上にさらに二つまで追加のモーダルをスタックに積み重ねることができます。