diff --git a/docs/.gitignore b/docs/.gitignore index b28443d42..5309e1783 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,4 @@ _site Gemfile.lock -.env \ No newline at end of file +.env +.jekyll-metadata diff --git a/docs/_tutorials/getting_started.md b/docs/_tutorials/getting_started.md index 8208435af..6594ba567 100644 --- a/docs/_tutorials/getting_started.md +++ b/docs/_tutorials/getting_started.md @@ -34,21 +34,19 @@ Look around, add an app icon and description, and then let's start configuring y ### Tokens and installing apps Slack apps use [OAuth to manage access to Slack's APIs](https://api.slack.com/docs/oauth). When an app is installed, you'll receive a token that the app can use to call API methods. -There are two token types available to a Slack app: user (`xoxp`) and bot (`xoxb`) tokens. User tokens allow you to call API methods on behalf of users after they install or authenticate the app. There may be several user tokens for a single workspace. Bot tokens are granted once in every workspace where someone installs the app, though they require adding a bot user to your app. The bot token your app uses will be the same no matter which user performed the installation. +There are two token types available to a Slack app: user (`xoxp`) and bot (`xoxb`) tokens. User tokens allow you to call API methods on behalf of users after they install or authenticate the app. There may be several user tokens for a single workspace. Bot tokens are associated with bot users, and are only granted once in a workspace where someone installs the app. The bot token your app uses will be the same no matter which user performed the installation. Bot tokens are the token type that _most_ apps use. For brevity, we're going to use bot tokens for this guide. -To add a bot user, 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**. +Navigate to the **OAuth & Permissions** on the left sidebar and scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. -Now that you have a bot user with permission to send messages to Slack, let's install the app to your workspace. +For now, we'll just add one scope: [`chat:write`](https://api.slack.com/scopes/chat:write). This grants your app the permission to post messages in channels it's a member of. -Click **Install App** on the left sidebar and click the **Install App to Workspace** button at the top of the page. You'll see a screen that details what permissions the app is requesting, which correlate to the scopes applied to your app's OAuth token(s). +Scroll up to the top of the OAuth & Permissions page and click **Install App to Workspace**. You'll be led through Slack's OAuth UI, where you should allow your app to be installed to your development workspace. -Once you authorize the installation, you'll land on the **OAuth & Permissions** page. +Once you authorize the installation, you'll land on the **OAuth & Permissions** page and see a **Bot User OAuth Access Token**. -![OAuth Tokens](../assets/bot-token.png "OAuth Tokens") - -You'll see two tokens. For now, we'll just use the `xoxb` bot token. (If you scroll down this page to the **Scopes** section, you'll see the various scopes you can add to the `xoxp` token.) +![OAuth Tokens](../assets/bot-token.png "Bot OAuth Token") > 💡 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. diff --git a/docs/_tutorials/ja_getting_started.md b/docs/_tutorials/ja_getting_started.md index ce925e05d..234bc9611 100644 --- a/docs/_tutorials/ja_getting_started.md +++ b/docs/_tutorials/ja_getting_started.md @@ -18,7 +18,7 @@ redirect_from: --- ### アプリを作成する -最初にやるべきこと: Bolt で開発を始める前に、 [Slack アプリを作成](https://api.slack.com/apps/new)します。 +最初にやるべきこと: Bolt で開発を始める前に、 [Slack アプリを作成](https://api.slack.com/apps/new)します。 > 💡 いつもの仕事のさまたげにならないように、別に開発用のワークスペースを使用することをお勧めします — [新しいワークスペースを無料で作成](https://slack.com/get-started#create)できます。 @@ -35,22 +35,20 @@ redirect_from: ### トークンとアプリのインストール Slack アプリは、[OAuth を使用して、Slack の API へのアクセスを管理](https://api.slack.com/docs/oauth)します。アプリがインストールされると、トークンを受け取ります。そのトークンを使って、アプリは API メソッドを呼び出すことができます。 -Slack アプリに使用できるトークンタイプは、user(`xoxp`) トークンと bot(`xoxb`) トークンの 2 つです。ユーザートークンを使用すると、ユーザーがアプリをインストールまたは認証した後で、ユーザーに代わって API メソッドを呼び出すことができます。単一のワークスペースに複数のユーザートークンが存在する場合があります。ボットトークンは、アプリがインストールされるすべてのワークスペースで 1 回付与されます。ただし、ボットトークンは、アプリにボットユーザーを追加する必要があります。どのユーザーがインストールを実行しても、アプリで使用されるボットトークンは同じになります。 +Slack アプリに使用できるトークンには、user(`xoxp`) トークンと bot(`xoxb`) トークンの 2 種類があります。ユーザートークンを使用すると、ユーザーがアプリをインストールまたは認証した後で、ユーザーに代わって API メソッドを呼び出すことができます。単一のワークスペースに複数のユーザートークンが存在する場合があります。ボットトークンはボットユーザーに紐づいており、ワークスペースの誰かがアプリをインストールするとそのワークスペースに 1 回付与されます。どのユーザーがインストールを実行しても、アプリで使用されるボットトークンは同じものになります。実際にはほとんどのアプリで使用されるトークンの種別はユーザートークンではなく、ボットトークンになるでしょう。 説明を簡潔にするために、このガイドではボットトークンを使用します。 -ボットユーザーを追加するには、左側のサイドバーの **Bot Users** をクリックしてから、**Add A Bot User** をクリックします。表示名とユーザー名を指定して、**Add Bot User** をクリックします。 +左側のサイドバーの **OAuth & Permissions** にアクセスして、**Bot Token Scopes** までスクロールします。そして、**Add an OAuth Scope** をクリックします。 -Slack へのメッセージの送信権限を持つボットユーザーが追加されたので、まずはワークスペースにアプリをインストールしましょう。 +とりあえずは、[`chat:write`](https://api.slack.com/scopes/chat:write) というスコープだけを追加してみましょう。これは、アプリにボットユーザがメンバーとして参加しているチャンネルへのメッセージの投稿を許可するスコープです。 -左側のサイドバーにある **Install App** をクリックし、ページ上部の **Install App to Workspace** ボタンをクリックします。アプリがリクエストしている権限の詳細を示す画面が表示されます。これは、アプリの OAuth トークンに適用されるスコープと相関しています。 +ページ上部までスクロールして戻り、**Install App to Workspace** をクリックします。すると、開発用のワークスペースにこのアプリをインストールするための Slack の OAuth 確認画面へと誘導されます。 -インストールを承認すると、**OAuth & Permissions** ページが表示されます。 +インストールを承認すると、**OAuth & Permissions** ページが表示され、**Bot User OAuth Access Token** を確認することができるはずです。 ![OAuth Tokens](../../assets/bot-token.png "OAuth Tokens") -2 つのトークンが表示されます。今回は`xoxb` ボットトークンを使用します。(このページを下にスクロールして **Scope** セクションを表示すると、`xoxp` トークンに追加できるさまざまなスコープが確認できます。) - > 💡 トークンは、パスワードのように大切に扱い、[安全に保管](https://api.slack.com/docs/oauth-safety)してください。アプリではそのトークンを使用して、Slack ワークスペースからの情報を投稿および取得します。 ### ローカルプロジェクトの設定 diff --git a/docs/assets/bot-token.png b/docs/assets/bot-token.png index 7b1ce700a..a4df255f3 100644 Binary files a/docs/assets/bot-token.png and b/docs/assets/bot-token.png differ