Merge branch 'main' into feat-workflow-steps

docs/_advanced/authorization.md

@@ -8,7 +8,7 @@ order: 2
 <div class="section-content">
 Authorization is the process of deciding which Slack credentials (such as a bot token) should be available while processing a specific incoming event.
 
-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.
+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. <b>If you're using the [built-in OAuth support](#authenticating-oauth) authorization is handled by default, so you do not need to pass in an `authorize` option.</b>
 
 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 event is coming from by using properties like `teamId` (always available), `userId`, `conversationId`, and `enterpriseId`.
 

docs/_basic/ja_listening_events.md

@@ -15,10 +15,9 @@ order: 3
 const welcomeChannelId = 'C12345';
 
 // 新しいユーザーがワークスペースに加入したタイミングで、指定のチャンネルにメッセージを送信して自己紹介を促す
-app.event('team_join', async ({ event, context }) => {
+app.event('team_join', async ({ event, client }) => {
   try {
-    const result = await app.client.chat.postMessage({
-      token: context.botToken,
+    const result = await client.chat.postMessage({
       channel: welcomeChannelId,
       text: `Welcome to the team, <@${event.user.id}>! 🎉 You can introduce yourself in this channel.`
     });

docs/_basic/ja_opening_modals.md

@@ -16,13 +16,12 @@ order: 10
 
 ```javascript
 // コマンド起動をリッスン
-app.command('/ticket', async ({ ack, body, context }) => {
+app.command('/ticket', async ({ ack, body, client }) => {
   // コマンドのリクエストを確認
   await ack();
 
   try {
-    const result = await app.client.views.open({
-      token: context.botToken,
+    const result = await client.views.open({
       // 適切な trigger_id を受け取ってから 3 秒以内に渡す
       trigger_id: body.trigger_id,
       // view の値をペイロードに含む

docs/_basic/ja_updating_pushing_modals.md

@@ -20,13 +20,12 @@ order: 11
 ```javascript
 // action_id: button_abc のボタンを押すイベントをリッスン
 // （そのボタンはモーダルの中にあるという想定）
-app.action('button_abc', async ({ ack, body, context }) => {
+app.action('button_abc', async ({ ack, body, client }) => {
   // ボタンを押したイベントを確認
   await ack();
 
   try {
-    const result = await app.client.views.update({
-      token: context.botToken,
+    const result = await client.views.update({
       // リクエストに含まれる view_id を渡す
       view_id: body.view.id,
       // 更新された view の値をペイロードに含む

docs/_basic/listening_events.md

@@ -15,10 +15,10 @@ The `event()` method requires an `eventType` of type string.
 const welcomeChannelId = 'C12345';
 
 // When a user joins the team, send a message in a predefined channel asking them to introduce themselves
-app.event('team_join', async ({ event, context }) => {
+app.event('team_join', async ({ event, client }) => {
   try {
-    const result = await app.client.chat.postMessage({
-      token: context.botToken,
+    // Call chat.postMessage with the built-in client
+    const result = await client.chat.postMessage({
       channel: welcomeChannelId,
       text: `Welcome to the team, <@${event.user.id}>! 🎉 You can introduce yourself in this channel.`
     });

docs/_basic/listening_responding_shortcuts.md

@@ -23,16 +23,14 @@ When configuring shortcuts within your app configuration, you'll continue to app
 
 ```javascript
 // The open_modal shortcut opens a plain old modal
-app.shortcut('open_modal', async ({ shortcut, ack, context, client }) => {
+app.shortcut('open_modal', async ({ shortcut, ack, client }) => {
 
   try {
     // Acknowledge shortcut request
     await ack();
 
     // Call the views.open method using one of the built-in WebClients
     const result = await client.views.open({
-      // The token you used to initialize your app is stored in the `context` object
-      token: context.botToken,
       trigger_id: shortcut.trigger_id,
       view: {
         type: "modal",
@@ -84,15 +82,13 @@ app.shortcut('open_modal', async ({ shortcut, ack, context, client }) => {
 
   ```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, context, client }) => {
+  app.shortcut({ callback_id: 'open_modal', type: 'message_action' }, async ({ shortcut, ack, client }) => {
     try {
       // Acknowledge shortcut request
       await ack();
 
       // Call the views.open method using one of the built-in WebClients
       const result = await client.views.open({
-        // The token you used to initialize your app is stored in the `context` object
-        token: context.botToken,
         trigger_id: shortcut.trigger_id,
         view: {
           type: "modal",

docs/_basic/opening_modals.md

@@ -15,13 +15,13 @@ Read more about modal composition in the <a href="https://api.slack.com/surfaces
 
 ```javascript
 // Listen for a slash command invocation
-app.command('/ticket', async ({ ack, body, context }) => {
+app.command('/ticket', async ({ ack, body, client }) => {
   // Acknowledge the command request
   await ack();
 
   try {
-    const result = await app.client.views.open({
-      token: context.botToken,
+    // Call views.open with the built-in client
+    const result = await client.views.open({
       // Pass a valid trigger_id within 3 seconds of receiving it
       trigger_id: body.trigger_id,
       // View payload

docs/_basic/updating_pushing_modals.md

@@ -19,13 +19,13 @@ Learn more about updating and pushing views in our <a href="https://api.slack.co
 
 ```javascript
 // Listen for a button invocation with action_id `button_abc` (assume it's inside of a modal)
-app.action('button_abc', async ({ ack, body, context }) => {
+app.action('button_abc', async ({ ack, body, client }) => {
   // Acknowledge the button request
   await ack();
 
   try {
-    const result = await app.client.views.update({
-      token: context.botToken,
+    // Call views.update with the built-in client
+    const result = await client.views.update({
       // Pass the view_id
       view_id: body.view.id,
       // View payload with updated blocks

docs/_basic/web_api.md

@@ -6,21 +6,21 @@ order: 4
 ---
 
 <div class="section-content">
-You can call [any Web API method](https://api.slack.com/methods) using the [`WebClient`](https://slack.dev/node-slack-sdk/web-api) provided to your Bolt app as `app.client` (given that your app has the appropriate scopes). When you call one the client's methods, it returns a Promise containing the response from Slack.
+You can call [any Web API method](https://api.slack.com/methods) using the [`WebClient`](https://slack.dev/node-slack-sdk/web-api) provided to your app's listeners as `client`. This uses either the token that initialized your app <b>or</b> the token that is returned from the [`authorize` function](#authorization) for the incoming event. The built-in [OAuth support](#authenticating-oauth) handles the second case by default.
 
-The token used to initialize Bolt can be found in the `context` object, which is required for most Web API methods.
+Your Bolt app also has a top-level `app.client` which you can manually pass the `token` parameter. If the incoming event 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://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.
 </div>
 
 ```javascript
 // Unix Epoch time for September 30, 2019 11:59:59 PM
 const whenSeptemberEnds = 1569887999;
 
-app.message('wake me up', async ({ message, context }) => {
+app.message('wake me up', async ({ message, client }) => {
   try {
-    // Call the chat.scheduleMessage method with a token
-    const result = await app.client.chat.scheduleMessage({
-      // The token you used to initialize your app is stored in the `context` object
-      token: context.botToken,
+    // Call chat.scheduleMessage with the built-in client
+    const result = await client.chat.scheduleMessage({
       channel: message.channel.id,
       post_at: whenSeptemberEnds,
       text: 'Summer has come and passed'

docs/_tutorials/getting_started.md

@@ -50,6 +50,8 @@ Once you authorize the installation, you'll land on the **OAuth & Permissions**
 
 > 💡 Treat your token like a password and [keep it safe](https://api.slack.com/docs/oauth-safety). Your app uses it to post and retrieve information from Slack workspaces.
 
+---
+
 ### Setting up your local project
 With the initial configuration handled, it's time to set up a new Bolt project. This is where you'll write the code that handles the logic for your app.
 

docs/_tutorials/ja_getting_started.md

@@ -51,6 +51,8 @@ Slack アプリに使用できるトークンには、user(`xoxp`) トークン
 
 > 💡 トークンは、パスワードのように大切に扱い、[安全に保管](https://api.slack.com/docs/oauth-safety)してください。アプリではそのトークンを使用して、Slack ワークスペースからの情報を投稿および取得します。
 
+---
+
 ### ローカルプロジェクトの設定
 初期設定が完了したので、次は新しい Bolt プロジェクトを設定します。ここで、アプリのロジックを処理するコードを記述します。