Merge pull request #244 from l4cr0ss/update_readme

First pass at README update

Author: Grazfather

README.md

@@ -50,49 +50,140 @@ Secondary features :
 !wolfram ask <question>                                         (Ask wolfram alpha a question)
 ```
 
-## Retrieving the API token
+## Retrieving the API tokens
 
 Bot applications are not allowed to access all api methods from Slack. Thus, if
 you create a bot integration on slack, the bot won't be able to create new
-channels for example. To get around this restriction, you have to create a real
-slack user and generate an authentication token for it, which can then be used
-instead of a bot token.
+channels for example. To get around this restriction you must create a new
+slack integration ("Slack App"), assign it to your workspace, enable the Socket
+Mode event feed, generate an "App Level Token" (`xapp1`), assign scopes to your
+bot user and subsequently create a "Bot User Token" (`xoxb`), and then finally
+install it to your workspace. 
 
-1. Create a new user in slack (this will be the bot user, so give it an appropriate username)
-2. Log into slack with this newly created user
-3. Navigate to https://api.slack.com/custom-integrations/legacy-tokens
-  * The user should show up there together with your slack workspace
-5. Press "Create token"
-  * This should create a token starting with "xoxp-"
-7. Use this token as the `api_key` for the bot
-8. Logout and login with your regular user again.
+Once generated, the tokens must be scoped to the appropriate privilege levels
+required for the bot to function. Finally, you must ensure that you have
+subscribed the bot users to the list of events it will need to receive in order
+to operate.
 
-After restarting the bot, the bot user should now show up in your slack workspace.
+1. First, navigate to `api.slack.com/apps` and create a new slack app. Give it
+a name and select the workspace that it will serve, and then click create.
+
+2. Enable socket mode by clicking on the menu of the same name and then
+clicking on the toggle labelled "Enable Socket Mode". You'll be prompted to
+create an App Level Token which you must do next.
+
+3. App Level Token
+
+This token is used by the bot to access the websocket event feed in version 3
+of the Slack API. The toggle you enabled in the previous step, "Enable Socket
+Mode", is what turns on the event feed. Assuming you've not already created an
+App Level Token you'll now be prompted to do so. Place it into the config file
+under the entry `app_key`.
+
+4. Bot User Token
+
+This token is used by the bot to interact with the workspace and users via
+Slack's conversations API. In order to create this token you must first
+navigate to the OAuth & Permissions section of the Slack API control panel.
+
+Once there, take note of the greyed out "Install to Workspace" button. You need
+to add scopes to the bot user's token before you can install the bot. Scroll
+down to the bottom of this page and in the section labelled "Bot Token Scopes"
+add the following scopes.
+
+```
+app_mentions:read
+channels:history
+channels:join
+channels:manage
+channels:read
+chat:write
+chat:write.customize
+chat:write.public
+dnd:read
+groups:history
+groups:read
+groups:write
+im:history
+im:read
+im:write
+links:read
+links:write
+mpim:history
+mpim:read
+mpim:write
+reactions:read
+reactions:write
+reminders:list
+reminders:write
+team:read
+users:read
+users:write
+```
+
+Next, return to the top of the page and install the bot user using the button
+from before which should no longer be greyed out. Now copy the "Bot User OAuth
+Access Token" (begins with `xoxb`) into the config file under the entry
+`api_key`. The bot should show up inside the workspace now. You can change its
+display name using the menu on the left labelled "Basic Information", if you
+want.
+
+5. Event subscription
+
+NOTE: Make sure you toggle "Enable Socket" (step 2) before attempting this!
+
+Once the tokens have been configured you will need to navigate to the Event
+Subscriptions panel of the slack API control panel and register the bot to
+receive the events it needs to operate. 
+
+First toggle the switch labelled "Enable Events", then use the picker to select
+at least the events below. They are probably all that you will need, but it's
+fine to select all of the event subscriptions here if you want to be on the simple side. 
+
+```
+app_mention
+app_mentions:read
+channels:history
+emoji_changed
+emoji:read
+groups:history
+im:history
+link_shared
+links:read
+message.channels
+message.im
+message.groups
+message.mpim
+mpim:history
+reaction_added
+reactions:read
+reaction_removed
+```
 
 
 ## Installation
 
-1. Copy `config/config.json.template` to `config/config.json`
-2. Fill the API token and bot name in the config.json file.
-3. Add your user id (slack id, not the username) to `admin_users` group in `config/config.json`
+1. Copy _config/config.json.template_ to _config/config.json_
+2. Fill the APP and API token names in the _config.json_ file.
+3. Add your user id (slack id, not the username) to `admin_users` group in _config/config.json_
 4. If you want to use the wolfram alpha api, register a valid app id on http://products.wolframalpha.com/api/ and set `wolfram_app_id` in `config/config.json`
-5. Copy `intro_msg.template` to `intro_msg` and set a proper introduction message, which can be shown with `!intro`
+5. Copy _intro_msg.template_ to _intro_msg_ and set a proper introduction message, which can be shown with `!intro`
 6. `docker build -t ota-challenge-bot .`
 7. `docker run -it --rm --name live-ota-challenge-bot ota-challenge-bot`
 
 
 ## Development
 
-1. Copy `config/config.json.template` to `config/config.json`
-2. Fill the API token and bot name in the config.json file.
+1. Copy _config/config.json.template_ to _config/config.json_
+2. Fill the API token and bot name in the _config.json_ file.
 3. Create a virtual env: `python3 -m venv .venv`
 4. Enter the virtual env: `source .venv/bin/activate`
 5. Install requirements: `pip install -r requirements.txt`
 
 
 ## Using git support for uploading solve updates
 
-1. Copy `config/config_solvetracker.json.template` to `config/config_solvetracker.json`.
+1. Copy _config/config_solvetracker.json.template_ to _config/config_solvetracker.json_.
 2. Configure the git account, the local repo and the remote path, which should be used to access your git repository.
 
 Example:
@@ -107,20 +198,20 @@ Example:
 }
 ```
 
-Alternatively, you may decide to omit the "git_repopass" entry. In such an event (or if the entry is left blank) then the handler will attempt to push to the configured "git_remoteuri" using the `git` protocol, including using any SSH identities you may have configured.
+Alternatively, you may decide to omit the `git_repopass` entry. In such an event (or if the entry is left blank) then the handler will attempt to push to the configured "git_remoteuri" using the `git` protocol, including using any SSH identities you may have configured.
 Note: If you configure the solvetracker this way, you need to make sure you are using an SSH identity without a passphrase.
 
 3. Update the templates in `templates` according to your preferences (or go with the default ones).
-4. Make sure that there's a `_posts` and `_stats` folder in your git repository.
+4. Make sure that there's a __posts_ and __stats_ folder in your git repository.
 5. You should be good to go now and git support should be active on the next startup. You can now use the `postsolves` command to push blog posts with the current solve status to git.
 
 
 ## Using Link saver
 
 1. Setup a github repo with jekyll and staticman (e.g. https://github.com/ujjwal96/links).
-2. Copy `config/config_savelink.json.template` to `config/config_savelink.json`.
+2. Copy _config/config_savelink.json.template_ to _config/config_savelink.json_.
 3. Configure the git repo and branch to be used.
-4. Add the decrypted staticman-token used in `staticman.yml` in the config.
+4. Add the decrypted staticman-token used in _staticman.yml_ in the config.
 5. Add a link to your repo, so people can look it up via `showlinkurl`
 
 Example:
@@ -136,7 +227,7 @@ Example:
 
 ## Archive reminder
 
-To enable archive reminders set an offset (in hours) in `config/config.json` for `archive_ctf_reminder_offset`. Clear or remove the setting to disable reminder handling.
+To enable archive reminders set an offset (in hours) in _config/config.json_ for `archive_ctf_reminder_offset`. Clear or remove the setting to disable reminder handling.
 
 If active, the bot will create a reminder for every bot admin on `!endctf` to inform him, when the ctf was finished for the specified time and it should be archived.
 
@@ -150,7 +241,7 @@ Example (for being reminded one week after the ctf has finished):
 
 ## Log command deletion
 
-To enable logging of deleting messages containing specific keywords, set `delete_watch_keywords` in `config/config.json` to a comma separated list of keywords. 
+To enable logging of deleting messages containing specific keywords, set `delete_watch_keywords` in _config/config.json_ to a comma separated list of keywords. 
 Clear or remove the setting to disable deletion logging.
 
 Example