From 9a7eabdd0e25b1c3b4314d5c7fdedafcdd555a95 Mon Sep 17 00:00:00 2001
From: rht <rhtbot@protonmail.com>
Date: Wed, 26 Aug 2020 01:57:43 -0400
Subject: [PATCH] Document Slack bridge.

---
 templates/zerver/integrations/slack.md | 73 ++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 templates/zerver/integrations/slack.md

diff --git a/templates/zerver/integrations/slack.md b/templates/zerver/integrations/slack.md
new file mode 100644
index 0000000000..7a56321f1b
--- /dev/null
+++ b/templates/zerver/integrations/slack.md
@@ -0,0 +1,73 @@
+Mirror a Slack channel in Zulip!
+
+If you only want to bridge one channel in Slack with one topic in Zulip, we
+recommend using [Matterbridge](https://github.com/42wim/matterbridge).
+If you want to bridge multiple channels in Slack with multiple topics in a
+Zulip stream, you may continue reading this guide.
+
+### Install the bridge software
+
+1. Clone the Zulip API repository, and install its dependencies.
+
+    ```
+    git clone https://github.com/zulip/python-zulip-api.git
+    cd python-zulip-api
+    python3 ./tools/provision
+    ```
+
+    This will create a new Python virtualenv. You'll run the bridge service
+    inside this virtualenv.
+
+1. Activate the virtualenv by running the `source` command printed
+   at the end of the output of the previous step.
+
+1. Go to the directory containing the bridge script if you haven't already done so
+   ```
+   cd zulip/integrations/bridge_with_slack
+   ```
+
+1. Install the bridge dependencies in your virtualenv, by running:
+    ```
+    pip install -r requirements.txt
+    ```
+
+### Configure the bridge
+
+1. In Zulip, [create a bot](/help/add-a-bot-or-integration), using **Generic bot**
+   for the bot type. Download the bot's `zuliprc` configuration file to your
+   computer.
+
+1. [Subscribe the bot](/help/add-or-remove-users-from-a-stream) to the Zulip
+   stream that will contain the mirror.
+
+1. Make sure Websocket isn't blocked in the computer where you run this bridge.
+   Test it at https://www.websocket.org/echo.html.
+
+1. Make sure you are signed in to the Slack workspace you want to mirror.
+
+1. Go to https://api.slack.com/apps?new_classic_app=1 and create a new classic
+   app (note: must be a classic app). You can choose any descriptive name you
+   want.
+
+1. Once created, go to the left sidebar, and click "App Home," and then click
+   "Add Legacy Bot User" Choose a bot username that will be put into
+   bridge_with_slack_config.py in the username field in the Slack section, e.g.
+   "zulip_mirror".
+
+1. On the left sidebar, click "Install App" and then click "Install to
+   Workspace." When successful, you should see a token that starts with
+   "xoxb-..." (there is also a token that starts with "xoxp-..."; we need the
+   "xoxb-..." one).
+
+1. Subscribe the Slack bot to the relevant channel. You can do this by typing
+   e.g. `/invite @zulip_mirror` in the relevant channel.
+
+1. Fill up `bridge_with_slack_config.py` with the relevant information
+
+1. Run the following command to start the Slack bridge:
+
+    ```
+    ./run-slack-bridge
+    ```
+
+If you have any questions, you can ask `@**Rein Zustand**` at https://chat.zulip.org.