slack connector: implemented signing secret and updated docs (#7186)

* implemented signing secret and updated docs * added changelog * Update docs/docs/connectors/slack.mdx * fixed missing file extension * fixed tests * Apply suggestions from code review Co-authored-by: Ella Rohm-Ensing <[email protected]> * added slack channel tests * Update slack.py * Apply suggestions from code review Co-authored-by: Tobias Wochinger <[email protected]> * implemented review comments Co-authored-by: Ella Rohm-Ensing <[email protected]> Co-authored-by: Tobias Wochinger <[email protected]>
RasaHQ · Nov 8, 2020 · aec2763 · aec2763
1 parent 9b937e6
commit aec2763
Show file tree

Hide file tree

Showing 14 changed files with 1,090 additions and 829 deletions.
diff --git a/changelog/7186.bugfix.md b/changelog/7186.bugfix.md
@@ -0,0 +1 @@
+Properly validate incoming webhook requests for the Slack connector to be authentic.
diff --git a/docs/docs/connectors/img/slack-create-app.png b/docs/docs/connectors/img/slack-create-app.png
diff --git a/docs/docs/connectors/img/slack-events.png b/docs/docs/connectors/img/slack-events.png
diff --git a/docs/docs/connectors/img/slack-install-app.png b/docs/docs/connectors/img/slack-install-app.png
diff --git a/docs/docs/connectors/img/slack-interactivity.png b/docs/docs/connectors/img/slack-interactivity.png
diff --git a/docs/docs/connectors/img/slack-request-url.png b/docs/docs/connectors/img/slack-request-url.png
diff --git a/docs/docs/connectors/img/slack-scopes.png b/docs/docs/connectors/img/slack-scopes.png
diff --git a/docs/docs/connectors/img/slack-secret.png b/docs/docs/connectors/img/slack-secret.png
diff --git a/docs/docs/connectors/slack.mdx b/docs/docs/connectors/slack.mdx
@@ -4,69 +4,167 @@ sidebar_label: Slack
 title: Slack
 description: Build a Rasa Chat Bot on Slack
 ---
+import createAppImg from './img/slack-create-app.png';
+import eventsImg from './img/slack-events.png';
+import installAppImg from './img/slack-install-app.png';
+import interactivityImg from './img/slack-interactivity.png';
+import requestUrlImg from './img/slack-request-url.png';
+import scopesImg from './img/slack-scopes.png';
+import secretImg from './img/slack-secret.png';
 
-You first have to create a Slack app to get credentials.
-Once you have them you can add these to your `credentials.yml`.
+Connecting a bot to Slack requires you to configure it to send messages
+(using API credentials) and to receive messages (using a webhook).
 
-## Getting Credentials
+## Sending Messages
 
-**How to get the Slack credentials:** You need to set up a Slack app.
+Create a new file `credentials.yml` in the root folder of your Rasa Open Source
+project (if you've used `rasa init` this file should already exist and you can
+just edit it). Add the following lines to the file:
+
+```yaml-rasa title="credentials.yml"
+slack:
+  slack_channel: "CA003L0XZ"    # channel ID, not a channel name!
+  slack_token: "xoxb-XXX"       # token obtained in the next step
+  slack_signing_secret: "YYY"   # secret obtained in the next step
+```
+
+The `slack_channel` can be a channel or an individual person that the bot should
+listen to for communications, in addition to the default behavior of listening
+for direct messages and app mentions, i.e. *@app_name*.
+To get a channel id, right click on the channel in Slack and choose **Copy Link**.
+The id will be the last component in the URL.
+
+In the next couple steps, you'll create a Slack App to get the values for
+`slack_token` and `slack_signing_secret`:
 
 1. To create the app go to [Your Apps](https://api.slack.com/apps "The Your Apps section of your Slack interface") and click
    on **Create New App**.
 
-2. Activate the following features:
+   <Image img={createAppImg} caption="Create New App" alt="Create New Slack App Screenshot" max-width="500px"/>
+
+   Fill out your **App Name** and select the **Development Workspace** where
+   you'll play around and build your app.
+
+2. Head over to **OAuth & Permissions** and scroll down to **Scopes**. Scopes give
+   your app permission to do things in your workspace.
+
+   To get started, you should at least add the following scopes:
+   - `app_mentions:read`,
+   - `channels:history`,
+   - `chat:write`,
+   - `groups:history`,
+   - `im:history`,
+   - `mpim:history` and
+   - `reactions:write`.
+
+   <Image img={scopesImg} caption="Set up Slack Permissions" alt="Set up Slack Permissions Screenshot" max-width="500px" />
+
+   In Slacks API documentation you can find a
+   [list and explanation of all available scopes](https://api.slack.com/scopes).
+
+3. On the **OAuth & Permissions** page, click **Install App to Workspace** to add
+   the bot to your workspace.
+
+   <Image img={installAppImg} caption="Install Slack App" alt="Install Slack App Screenshot" max-width="500px"/>
+
+   Once added, Slack will show you a **Bot User OAuth Access Token** which you'll
+   need to add to your `credentials.yml` as the value for `slack_token`:
+
+   ```yaml-rasa title="credentials.yml" line={3}
+   slack:
+     slack_channel: "your-channel" # choose a channel for your bot
+     slack_token: "xoxb-XXX"       # token obtained in the next step
+     slack_signing_secret: "YYY"   # secret obtained in the next step
+   ```
+
+   The token should start with `xoxb`.
 
-* Interactivity & Shortcuts > Interactivity (if your bot uses any
-  [interactive components](https://api.slack.com/reference/block-kit/interactive-components "The Interactive Components section of your Slack interface") , e.g. buttons)
+4. Head over to **Basic Information** to gather the **Signing Secret**.
 
-* Add your Rasa request URL `http://<host>:<port>/webhooks/slack/webhook`, replacing
-  the host and port with the appropriate values from your running Rasa X or Rasa Open Source server.
+   <Image img={secretImg} caption="Signing Secret" alt="Signing Secret Screenshot" max-width="500px"/>
 
-* Event subscriptions > Subscribe to bot events: `message.channels`, `message.groups`, `message.im`, `message.mpim`
+   Copy the signing secret into your `credentials.yml` as the value for `slack_signing_secret`:
 
-* App Home > Always Show My Bot as Online
+   ```yaml-rasa title="credentials.yml" line={4}
+   slack:
+     slack_channel: "your-channel" # choose a channel for your bot
+     slack_token: "xoxb-XXX"       # token obtained in the next step
+     slack_signing_secret: "YYY"   # secret obtained in the next step
+   ```
 
-1. Get the `Bot User OAuth Access Token` from the OAuth & Permissions page. Click `Install App to Workspace`
-   and allow access to your workspace. You will need
-   to provide this value in your credentials later in these instructions. It should start
-   with `xoxb`.
+This setup will allow your bot to send messages. Now let's head over to the setup
+for receiving and reacting to messages.
 
-2. In the “OAuth & Permissions > Redirect URLs” enter the endpoint for receiving Slack messages. This is
-   the same URL you entered above for Interactivity & Shortcuts - `http://<host>:<port>/webhooks/slack/webhook`.
+## Receiving Messages
+Before continuing, make sure you have configured a Slack App for [Sending Messages](./slack.mdx#sending-messages) and have added Slack credentials to your `credentials.yml` file.
 
-3. Configure your `credentials.yml` with the new Slack credentials as described in the
-   [Running on Slack](./slack.mdx#running-on-slack) section, and restart your server. This will allow
-   your server to confirm that the endpoint is ready to receive events. Once you've restarted the server,
-   go to the “Event Subscriptions” section, turn on the “Enable Events” and add the endpoint as the Request URL.
+To receive messages, you will need a publicly available URL for Slack to reach
+your bot and tell you about new messages. If you are running locally, you can
+[test channels using ngrok](../messaging-and-voice-channels.mdx#testing-channels-on-your-local-machine)
 
-For more detailed steps, visit the
-[Slack API docs](https://api.slack.com/events-api).
+1. To configure your bot to receive messages, your bot needs to be running.
+   Start your bot e.g. using
+   ```bash
+   rasa run
+   ```
+   If you are running locally, make sure ngrok (or another tool to retrieve a public
+   url) is running as well.
 
-## Running on Slack
+2. Configure the webhook by heading to **Event Subscriptions** and
+   turning **Enable Events** on.
 
-Add the Slack credentials to your `credentials.yml`:
+   As a request URL enter the public url of your bot and append `/webhooks/slack/webhook`, e.g.
+   `https://<host>/webhooks/slack/webhook` replacing `<host>` with your URL. If you
+   are using ngrok, your url should look like `https://92832de0.ngrok.io/webhooks/slack/webhook`.
 
-```yaml-rasa
+   You won't be able to use a `localhost` url.
+
+   <Image img={requestUrlImg} caption="Request URL" alt="Request URL Screenshot" max-width="500px"/>
+
+3. As a last step, you'll need to **Subscribe to bot events** on the same page.
+   You'll need to add the following events:
+   - `message.channels`,
+   - `message.groups`,
+   - `message.im` and
+   - `message.mpim`.
+
+   <Image img={eventsImg} caption="Subscribe to Bot Events" alt="Subscribe to Bot Events Screenshot" max-width="500px"/>
+
+   Make sure to hit **Save Changes** at the bottom of the page after you've added these events.
+
+   (If you didn't grant all required permissions to your app while setting up
+   sending of messages, you'll be prompted to **reinstall your app** which you will
+   need to do. Otherwise, Slack will confirm your change with a **Success!**)
+
+Your bot is now ready to go and will receive webhook notifications about new messages.
+## Optional: Interactive Components
+After you've completed [Sending Messages](./slack.mdx#sending-messages) and
+[Receiving Messages](./slack.mdx#receiving-messages) your bot is ready to go. If you
+want to use Slack's [interactive components](https://api.slack.com/block-kit/interactivity) (buttons or menus), you'll need to do
+some additional configuration:
+
+Open the **Interactivity & Shortcuts** page and toggle **Interactivity** to be on.
+Afterwards, you'll need to enter the same url into the **Request URL** field which
+you used in Step 2 of [Receiving Messages](./slack.mdx#receiving-messages), e.g. `https://<host>/webhooks/slack/webhook`.
+
+<Image img={interactivityImg} caption="Enabling Interactivity" alt="Interactivity Screenshot" max-width="500px"/>
+
+## Additional Slack Options
+
+Here is a complete overview of all the configuration parameters for the Slack
+connection:
+
+```yaml-rasa title="credentials.yml"
 slack:
-  slack_token: "xoxb-286425452756-safjasdf7sl38KLls"
-  slack_channel: "C011GR5D33F"
-  proxy: "http://myProxy.online"  # Proxy Server to route your traffic through. This configuration is optional.
+  slack_channel: "CA003L0XZ"    # channel ID, not a channel name!
+  slack_token: "xoxb-XXX"       # token obtained in the next step
+  slack_signing_secret: "YYY"   # secret obtained in the next step
+  proxy: "http://myProxy.online"  # Proxy Server to route your traffic through. This configuration is optional. Only HTTP proxies are supported
   slack_retry_reason_header: "x-slack-retry-reason"  # Slack HTTP header name indicating reason that slack send retry request. This configuration is optional.
   slack_retry_number_header: "x-slack-retry-num"  # Slack HTTP header name indicating the attempt number. This configuration is optional.
   errors_ignore_retry: None  # Any error codes given by Slack included in this list will be ignored. Error codes are listed [here](https://api.slack.com/events-api#errors).
   use_threads: False  # If set to True, bot responses will appear as a threaded message in Slack. This configuration is optional and set to False by default.
 ```
 
-* The `slack_channel` can be a channel or an individual person that the bot should listen to for communications, in
-  addition to the default behavior of listening for direct messages and app mentions, i.e. “@app_name”. To get the channel
-  id, right click on the channel choose Copy Link and the id will be the last component in the URL.
-
-* Use the entry for `Bot User OAuth Access Token` in the
-  “OAuth & Permissions” tab as your `slack_token`. It should start
-  with `xoxb`.
-
-* Optional: You can add a `proxy` through which to route outgoing traffic to the Slack API. Only HTTP proxies are currently supported.
-
-Restart your Rasa X or Rasa Open Source server
-to make the new channel endpoint available for Slack to send messages to.
+Make sure to restart your Rasa X or Rasa Open Source server after changing the
+`credentials.yml` for the changes to take effect.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Properly validate incoming webhook requests for the Slack connector to be authentic.