From b6aa246f7c5cfa66078efffccb02d8d621224988 Mon Sep 17 00:00:00 2001
From: Udo Rader <udo.rader@bestsolution.at>
Date: Mon, 13 Apr 2020 17:17:19 +0200
Subject: [PATCH] better described how to get channel id, added a section how
 to unlink a channel and a troubleshooting section

---
 ...guring-playbook-bridge-appservice-slack.md | 35 ++++++++++++++++---
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md
index cf087414..371195b6 100644
--- a/docs/configuring-playbook-bridge-appservice-slack.md
+++ b/docs/configuring-playbook-bridge-appservice-slack.md
@@ -4,7 +4,7 @@ The playbook can install and configure [matrix-appservice-slack](https://github.
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-Setup Instructions:
+## Setup Instructions:
 
 loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
 
@@ -29,7 +29,9 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
 
 5. Create a new Slack App [here](https://api.slack.com/apps).
 
-    Name the app & select the team/workspace this app will belong to.
+    Name the app "matrixbot" (or anything else you'll remember).
+
+    Select the team/workspace this app will belong to.
 
     Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
 
@@ -61,9 +63,9 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
 
     * Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF:example.com.
 
-    * Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @slackbot` for slack and `/invite @slackbot:MY.DOMAIN` for matrix.
+    * Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for slack and `/invite @slackbot:MY.DOMAIN` for matrix.
 
-    * Determine the "channel ID" that Slack uses to identify the channel, which can be found in the url `https://XXX.slack.com/messages/<the channel id you need>/`. Or, even simpler, if you open a channel in a browser, the URL reads like this: `https://app.slack.com/client/XXX/<the channel id you need>/details/`.
+    * Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel id>/details/`.
 
     * Issue a link command in the administration control room with these collected values as arguments:
 
@@ -81,3 +83,28 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
     ```
 
 Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
+
+10. Unlinking
+
+    Channels can be unlinked again like this:
+    ```
+       unlink --room !the-matrix:room.id
+    ```
+
+    Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
+
+## Troubleshooting
+
+* as always, check the logs:
+`journalctl -fu matrix-appservice-slack`
+
+* linking: "Room is now pending-name"
+This typically means that you haven't used the correct slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.
+
+* Messages work from M to S, but not the other way around
+Check you logs, if they say something like
+
+`WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) <the channel id> <some other id>`
+
+then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link 
+your room multiple times without unlinking it after each failed attempt.