---
id: slack
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';
import appHomeImg from './img/slack-create-app.png';

Connecting a bot to Slack requires you to configure it to send messages
(using API credentials) and to receive messages (using a webhook).

## Sending Messages

Create a new file `credentials.yml` in the root folder of your Rasa
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**.

   <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`.

4. Head over to **Basic Information** to gather the **Signing Secret**.

   <Image img={secretImg} caption="Signing Secret" alt="Signing Secret Screenshot" max-width="500px"/>

   Copy the signing secret into your `credentials.yml` as the value for `slack_signing_secret`:

   ```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
   ```

This setup will allow your bot to send messages. Now let's head over to the setup
for receiving and reacting to messages.

## 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.

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)

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.

2. To send messages directly to your bot using the slack UI, head to **App Home**,
   scroll to the bottom and select the checkbox for
   `Allow users to send Slash commands and messages from the messages tab.`

   You might have to quit the Slack app and re-open it before your changes take effect.

   <Image img={appHomeImg} caption="Messages Tab" alt="Allow users to send Slash commands and messages from the messages tab" max-width="500px"/>

3. Configure the webhook by heading to **Event Subscriptions** and
   turning **Enable Events** on.

   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`.

   You won't be able to use a `localhost` url.

   <Image img={requestUrlImg} caption="Request URL" alt="Request URL Screenshot" max-width="500px"/>

4. 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!**)

:::note invite to channels
As per [Slack docs](https://api.slack.com/authentication/basics#calling), make
sure you invite your bot to a channel it should be accessing. You can do this
by using `/invite` in the channel.
:::

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_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.
  conversation_granularity: "sender" # sender allows 1 conversation per user (across channels), channel allows 1 conversation per user per channel, thread allows 1 conversation per user per thread. This configuration is optional and set to sender by default.
```

Make sure to restart your Rasa server after changing the
`credentials.yml` for the changes to take effect.
