slack-integration: Update Slack integration documentation.

The doc now shows instructions to setup the integration using
Slack's Events API instead of the legacy Outgoing webhook
service.

Co-authored-by: Alya Abbott <alya@zulip.com>
Co-authored-by: Lauryn Menard <lauryn@zulip.com>

zerver/webhooks/slack/doc.md

@@ -1,34 +1,79 @@
-Get Zulip notifications from Slack for messages on your team's
-public channels!
+# Zulip Slack integration
 
-See also the [Slack-compatible webhook](/integrations/doc/slack_incoming).
+Get Zulip notifications for messages on your team's public Slack
+channels! You can choose to map each **Slack channel** either to a
+**Zulip topic** or to a **Zulip channel**.
 
-1. {!create-channel.md!}
+See also the [Zulip Slack incoming webhook integration][1].
+
+!!! warn ""
+
+    Using [Slack's legacy Outgoing Webhook service][5] is no longer
+    recommended. Follow these instructions to switch to the new
+    [Slack Events API][3].
+
+{start_tabs}
+
+1. To map each Slack channel to a Zulip topic, [create one channel][2]
+   you'd like to use for Slack notifications. Otherwise, for each public
+   Slack channel, [create a Zulip channel][2] with the same name.
 
 1. {!create-an-incoming-webhook.md!}
 
-1. {!generate-integration-url.md!}
+1. {!generate-webhook-url-basic.md!}
 
-    If you'd like to map Slack channels to different topics within the same
-    channel, add `&channels_map_to_topics=1` to the end of the URL. Note that
-    this should be used instead of specifying a topic in the URL. If a topic
-    is specified in the URL, then it will be prioritized over the channel to
-    topic mapping.
+    To map each Slack channel to a Zulip topic, make sure that the
+    **Send all notifications to a single topic** option is disabled
+    when generating the URL. Add `&channels_map_to_topics=1` to the
+    generated URL.
 
-    If you'd like to map Slack channels to different channels, add
-    `&channels_map_to_topics=0` to the end of the URL. Make sure you create
-    channels for all your public Slack channels *(see step 1)*, and that the
-    name of each channel is the same as the name of the Slack channel it maps
-    to. Note that in this case, the channel to channel mapping will be
-    prioritized over the channel specified in the URL.
+    Otherwise, add `&channels_map_to_topics=0` to the generated URL.
+    Note that any Zulip channel you specified when generating the URL
+    will be ignored in this case.
 
-1. Go to <https://my.slack.com/services/new/outgoing-webhook>
-   and click **Add Outgoing WebHooks integration**.
+1. Create a new [Slack app][4], and open it. Navigate to the **OAuth
+   & Permissions** menu, and scroll down to the **Scopes** section.
 
-1. Scroll down and configure the **Channel** and/or **Trigger Word(s)**
-   options as appropriate. Set **URL(s)** to the URL constructed above,
-   and click **Save Settings**.
+1. Make sure **Bot Token Scopes** includes `channels:read`,
+   `channels:history`, `users:read`, `emoji:read`, `team:read`,
+   `users:read`, and `users:read.email`.
+
+    !!! tip ""
+
+        See [Slack's Events API documentation][3] for details about
+        these scopes.
+
+1. Scroll to the **OAuth Tokens for Your Workspace** section in the
+   same menu, and click **Install to Workspace**.
+
+1. The **Bot User OAuth Token** should be available now. Note it down as
+   `BOT_OAUTH_TOKEN`, and add it to the end of the URL you generated
+   above as: `&slack_app_token=BOT_OAUTH_TOKEN`.
+
+1. Go to the **Event Subscriptions** menu, toggle **Enable Events**,
+   and enter the URL with the bot user token in the **Request URL**
+   field.
+
+1. In the same menu, scroll down to the **Subscribe to bot events**
+   section, and click on **Add Bot User Event**. Select the
+   `message.channels` event.
+
+{end_tabs}
 
 {!congrats.md!}
 
 ![](/static/images/integrations/slack/001.png)
+
+### Related documentation
+
+- [Slack Events API documentation][3]
+
+- [Slack Apps][4]
+
+{!webhooks-url-specification.md!}
+
+[1]: /integrations/doc/slack_incoming
+[2]: /help/create-a-channel
+[3]: https://api.slack.com/apis/events-api
+[4]: https://api.slack.com/apps
+[5]: https://api.slack.com/legacy/custom-integrations/outgoing-webhooks