Document usage of session tokens

Fixes #764

3 files changed, 63 insertions, 20 deletions

diff --git a/README.md b/README.md
index fc136d3..9ecea5a 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,11 @@ Table of Contents
      * [1. Install dependencies](#1-install-dependencies)
      * [2. Download wee_slack.py to ~/.weechat/python](#2-download-wee_slackpy-to-weechatpython)
      * [3. Start WeeChat](#3-start-weechat)
-     * [4. Add your Slack API key(s)](#4-add-your-slack-api-keys)
+     * [4. Add your Slack API token(s)](#4-add-your-slack-api-tokens)
+        * [Get a token with OAuth](#get-a-token-with-oauth)
+        * [Get a session token](#get-a-session-token)
         * [Optional: Connecting to multiple teams](#optional-connecting-to-multiple-teams)
+        * [Optional: Secure the tokens](#optional-secure-the-tokens)
   * [Commands and options](#commands-and-options)
      * [Threads](#threads)
      * [Emoji characters and tab completions of emoji names](#emoji-characters-and-tab-completions-of-emoji-names)
@@ -98,7 +101,24 @@ weechat
 
 **NOTE:** If weechat is already running, the script can be loaded using `/python load wee_slack.py`.
 
-### 4. Add your Slack API key(s)
+### 4. Add your Slack API token(s)
+
+There are two types of tokens that can be used, OAuth tokens and session
+tokens. The official way to get a token is to use OAuth. However, this has
+several drawbacks, so an alternative way is to pull a session token out of the
+web client.
+
+Drawbacks of OAuth tokens:
+- If the team is restricting app installations, wee-slack has to be approved by an admin.
+- For free teams, wee-slack will use one of the ten app slots.
+- The subscribe and unsubscribe commands won't work.
+- Marking threads, shared channels and channels that has been converted from public to private as read won't work.
+
+Drawbacks of session tokens:
+- These tokens can't be revoked, so be careful not to loose them.
+- They are not officially supported, and may stop working at any time.
+
+#### Get a token with OAuth
 
 Log in to Slack:
 
@@ -128,19 +148,12 @@ Note that by default GitHub Pages will see a temporary code used to create your
 token (but not the token itself). If you're worried about this, you can use the
 `-nothirdparty` option, though the process will be a bit less user friendly.
 
-The tokens you add will be stored in the option
-`plugins.var.python.slack.slack_api_token`. If you don't want to store your API
-token in plaintext you can use the secure features of WeeChat:
-
-```
-/secure passphrase this is a super secret password
-/secure set slack_token <YOUR_SLACK_TOKEN>
-/set plugins.var.python.slack.slack_api_token ${sec.data.slack_token}
-```
+#### Get a session token
 
-Note that you will have to move your tokens manually from
-`plugins.var.python.slack.slack_api_token` to the secure variable after each
-time you run `/slack register <code>`.
+1. Open and sign into the [Slack customization page](https://my.slack.com/customize). Check that you end up on the correct team.
+2. Type `javascript:` in the address field in the browser and paste this code after: `window.prompt("Session token:", TS.boot_data.api_token)`
+3. A prompt with the token will appear. Copy the token, return to WeeChat and run `/slack register <token>`.
+4. Reload the script with `/python reload slack`.
 
 #### Optional: Connecting to multiple teams
 
@@ -152,6 +165,22 @@ commas.
 /set plugins.var.python.slack.slack_api_token <token1>,<token2>,<token3>
 ```
 
+#### Optional: Secure the tokens
+
+The tokens you add will be stored as plain text in the option
+`plugins.var.python.slack.slack_api_token`. If you don't want to store your API
+token in plain text you can use the secure features of WeeChat:
+
+```
+/secure passphrase this is a super secret password
+/secure set slack_token <YOUR_SLACK_TOKEN>
+/set plugins.var.python.slack.slack_api_token ${sec.data.slack_token}
+```
+
+Note that you will have to move your tokens manually from
+`plugins.var.python.slack.slack_api_token` to the secure variable after each
+time you run `/slack register <code>`.
+
 Commands and options
 --------------------
 
diff --git a/docs/Commands.md b/docs/Commands.md
index 8ba5dc3..a972d19 100644
--- a/docs/Commands.md
+++ b/docs/Commands.md
@@ -164,9 +164,11 @@ Prints current status if no arguments are given, unsets the status if -delete is
 /slack subscribe <thread>
 ```
 
-Subscribe to a thread, so that you are alerted to new messages.  When in a
+Subscribe to a thread, so that you are alerted to new messages. When in a
 thread buffer, you can omit the thread id.
 
+Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens"
+
 ### talk
 
 ```
@@ -199,9 +201,11 @@ If no message id is specified the last thread in channel will be opened.
 ```
 
 Unsubscribe from a thread that has been previously subscribed to, so that
-you are not alerted to new messages.  When in a thread buffer, you can omit
+you are not alerted to new messages. When in a thread buffer, you can omit
 the thread id.
 
+Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens"
+
 ### upload
 
 ```
diff --git a/wee_slack.py b/wee_slack.py
index d6b5763..097cf37 100644
--- a/wee_slack.py
+++ b/wee_slack.py
@@ -2947,12 +2947,18 @@ def handle_subscriptionsthreadmark(json, eventrouter, team, channel, metadata):
 
 def handle_subscriptionsthreadadd(json, eventrouter, team, channel, metadata):
     if not json["ok"]:
-        print_error("Couldn't add thread subscription: {}".format(json['error']))
+        if json['error'] == 'not_allowed_token_type':
+            print_error("Can only subscribe to a thread when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens")
+        else:
+            print_error("Couldn't add thread subscription: {}".format(json['error']))
 
 
 def handle_subscriptionsthreadremove(json, eventrouter, team, channel, metadata):
     if not json["ok"]:
-        print_error("Couldn't remove thread subscription: {}".format(json['error']))
+        if json['error'] == 'not_allowed_token_type':
+            print_error("Can only unsubscribe from a thread when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens")
+        else:
+            print_error("Couldn't remove thread subscription: {}".format(json['error']))
 
 
 ###### New/converted process_ and subprocess_ methods
@@ -4275,8 +4281,10 @@ def subscribe_helper(current_buffer, args, usage, api):
 def command_subscribe(data, current_buffer, args):
     """
     /slack subscribe <thread>
-    Subscribe to a thread, so that you are alerted to new messages.  When in a
+    Subscribe to a thread, so that you are alerted to new messages. When in a
     thread buffer, you can omit the thread id.
+
+    Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens"
     """
     return subscribe_helper(current_buffer, args, 'Usage: /slack subscribe <thread>', "subscriptions.thread.add")
 
@@ -4289,8 +4297,10 @@ def command_unsubscribe(data, current_buffer, args):
     """
     /slack unsubscribe <thread>
     Unsubscribe from a thread that has been previously subscribed to, so that
-    you are not alerted to new messages.  When in a thread buffer, you can omit
+    you are not alerted to new messages. When in a thread buffer, you can omit
     the thread id.
+
+    Only works when using a session token, see the readme: https://github.com/wee-slack/wee-slack#4-add-your-slack-api-tokens"
     """
     return subscribe_helper(current_buffer, args, 'Usage: /slack unsubscribe <thread>', "subscriptions.thread.remove")