docs: clarify info about slack bot token

Author: yasunariw

README.md

@@ -36,7 +36,7 @@ Run the `_build/default/src/monorobot.exe` binary. The following commands are su
     1. [Create a Slack app](https://api.slack.com/apps?new_app=1).
     2. Click "Install to Workspace", and when prompted to grant permissions to your workspace, click "Allow".
     3. Set up notifications with one of the following methods:
-        - **Web API (recommended):** To use Slack's [Web API](https://api.slack.com/web), click on "OAuth & Permissions" in your app dashboard's sidebar. Give your bot a *Bot Token Scope* of [`chat:write`](https://api.slack.com/scopes/chat:write) (for per-channel authorization) or [`chat:write.public`](https://api.slack.com/scopes/chat:write.public) (for authorization to all channels). Copy the generated OAuth access token (`xoxb-XXXX`) to the `slack_access_token` field of your secrets file. This token is used by the bot to authenticate to the workspace, and remains valid until the token is revoked or the app is uninstalled. If you use the `chat:write` scope, add the bot to each channel you want to notify.
+        - **Web API (recommended):** To use Slack's [Web API](https://api.slack.com/web), click on "OAuth & Permissions" in your app dashboard's sidebar. Give your bot a *Bot Token Scope* of [`chat:write`](https://api.slack.com/scopes/chat:write) (for per-channel authorization) or [`chat:write.public`](https://api.slack.com/scopes/chat:write.public) (for authorization to all channels). Copy the generated bot token (`xoxb-XXXX`) to the `slack_access_token` field of your secrets file. This token is used by the bot to authenticate to the workspace, and remains valid until the token is revoked or the app is uninstalled. If you use the `chat:write` scope, add the bot to each channel you want to notify.
         - **Incoming Webhooks:** To use [incoming webhooks](https://api.slack.com/messaging/webhooks), enable them in your app dashboard and create one for each channel you want to notify. Store them in the `slack_hooks` field of your secrets file. If you decide to notify additional channels later, you will need to update the secrets file with the new webhooks and restart the server.
 
 

documentation/secret_docs.md

@@ -37,7 +37,13 @@ Required for:
 - Notification sending via Web API
 - Link unfurling
 
-Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.
+You can obtain a bot token from the "OAuth & Permissions" in your app dashboard's sidebar. Note that you need a *bot* token (`xoxb-XXXX`), not a *user* token (`xoxp-XXXX`).
+See [here](https://api.slack.com/authentication/basics#start) for creating/installing an app and requesting scopes.
+
+Give it the following scopes:
+- For notifications - [`chat:write`](https://api.slack.com/scopes/chat:write) (per-channel authorization) or [`chat:write.public`](https://api.slack.com/scopes/chat:write.public) (authorization to all channels)
+    - Note: If you use the `chat:write` scope, add the bot to each channel you want to notify.
+- For link unfurling - [`links:read`](https://api.slack.com/scopes/links:read) and [`links:write`](https://api.slack.com/scopes/links:write) (also see **Link Unfurling** in main README)
 
 ## `slack_hooks`
 

lib/config.atd

@@ -45,7 +45,7 @@ type secrets = {
   ?gh_hook_token : string nullable;
   (* list of Slack webhook & channel name pairs *)
   ~slack_hooks <ocaml default="[]"> : webhook list;
-  (* Slack bot token obtained via OAuth, enabling message posting to the workspace *)
+  (* Slack bot token (`xoxb-XXXX`), giving the bot capabilities to interact with the workspace *)
   ?slack_access_token : string nullable;
  (* Slack uses this secret to sign requests; provide to verify incoming Slack requests *)
   ?slack_signing_secret : string nullable;