> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellofriday.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Connect a Slack app to a space for DMs and @mentions.

Connect a Slack app to any Friday space so users can chat with it over DM or `@mentions`. Messages flow into the same conversation pipeline the web chat uses, and replies go back to Slack.

## Prerequisites

* A Slack space where you can install apps (admin, or one that allows member-installed apps).
* Friday running with the bundled tunnel active (Slack requires a public HTTPS URL).

## Setup

<Steps>
  <Step title="Grab your tunnel URL">
    Open Studio → **Settings** → **Webhook tunnel** and copy the URL — something like `https://<random>.trycloudflare.com`. Keep it handy for the next step.
  </Step>

  <Step title="Create the Slack app from a manifest">
    1. Open [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** → **From a manifest**.

    2. Pick the Slack space you want to install into.

    3. Paste the manifest below, replacing `<your-tunnel>` with the tunnel host from the previous step:

       ```json theme={null}
       {
         "display_information": { "name": "friday-bot" },
         "features": {
           "app_home": {
             "messages_tab_enabled": true,
             "messages_tab_read_only_enabled": false
           },
           "bot_user": { "display_name": "friday-bot", "always_online": true }
         },
         "oauth_config": {
           "scopes": {
             "bot": [
               "app_mentions:read", "chat:write", "chat:write.public",
               "channels:history", "channels:read", "groups:history", "groups:read",
               "im:history", "im:read", "im:write",
               "mpim:history", "mpim:read", "mpim:write",
               "reactions:write", "users:read"
             ]
           }
         },
         "settings": {
           "event_subscriptions": {
             "request_url": "https://<your-tunnel>.trycloudflare.com/platform/slack",
             "bot_events": ["message.im", "app_mention"]
           },
           "org_deploy_enabled": false,
           "socket_mode_enabled": false,
           "token_rotation_enabled": false
         }
       }
       ```

    4. Click **Next** → **Create**. Slack provisions scopes, event subscriptions, and the App Home messages tab from the manifest.
  </Step>

  <Step title="Install the app and copy three values">
    1. Go to **OAuth & Permissions** and click **Install to Space**. Approve the OAuth prompt.
    2. From the app dashboard, copy:
       * **App ID** — under *Basic Information* → *App Credentials*
       * **Signing Secret** — same section, click **Show** to reveal
       * **Bot User OAuth Token** — starts with `xoxb-…`, under *OAuth & Permissions*

    <Warning>
      Use the *Bot* OAuth Token (`xoxb-...`), not the *User* OAuth Token. They look similar but serve different purposes.
    </Warning>
  </Step>

  <Step title="Connect Slack in Studio">
    1. In Studio, select your space from the sidebar and click **Info**.
    2. Find the **Communicators** card and click **Connect** next to **Slack**.
    3. Paste the **App ID**, **Signing Secret**, and **Bot Token** into the form, then submit.

    Studio stores the credentials securely and wires the webhook for you. The status flips to **Connected** when it's done.
  </Step>

  <Step title="Verify the Request URL">
    Back in Slack's **Event Subscriptions**, the Request URL should report
    **Verified** once Friday is running. If it shows a yellow banner, click
    **Retry**.
  </Step>

  <Step title="Talk to your bot">
    1. In Slack, find the app under **Apps** in the sidebar, or DM it by name.
    2. Send a message. The first message creates a chat in the space — it should appear in Studio with a blue **SLACK** badge, and replies flow back to Slack automatically.
    3. To talk to the bot in a channel, invite it first (`/invite @bot-name`), then `@bot-name hello`.

    <Warning>
      **You must `@`-mention the bot every time you message it in a channel.** A plain message in a channel where the bot is present will not reach Friday. DMs to the bot don't need the mention.
    </Warning>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Slack shows 'Your URL didn't respond' during verification">
    Check that the tunnel is running — Studio → **Settings** → **Webhook tunnel** should show **active** with a URL. If the tunnel just restarted, Cloudflare assigns a new URL — paste the fresh one into the manifest's `request_url`.
  </Accordion>

  <Accordion title="Request URL verifies, but messages don't trigger anything">
    Double-check that you connected Slack in Studio for **this** space, and that
    the App ID you pasted matches the one in Slack's *Basic Information*.
  </Accordion>

  <Accordion title="Signature verification fails">
    The Signing Secret you pasted doesn't match the current one. In the Slack app
    dashboard click **Show** under *Signing Secret*, copy fresh, and reconnect via
    Studio.
  </Accordion>

  <Accordion title="Bot doesn't respond to @mentions in channels">
    Invite the bot to the channel first (`/invite @bot-name`).
  </Accordion>
</AccordionGroup>

## Configure via YAML

For CI or fully scripted setups, paste credentials directly into `workspace.yml` or the `.env` file in the Friday home directory (default `~/.friday/local/.env`). `app_id` is always required.

<Tabs>
  <Tab title="Credentials inline">
    ```yaml workspace.yml theme={null}
    communicators:
      slack:
        kind: slack
        app_id: A01234567
        bot_token: xoxb-...
        signing_secret: <signing secret>
    ```
  </Tab>

  <Tab title="Credentials via env">
    ```bash # Friday home .env (default ~/.friday/local/.env) theme={null}
    SLACK_BOT_TOKEN=xoxb-...
    SLACK_SIGNING_SECRET=<signing secret>
    ```

    ```yaml workspace.yml theme={null}
    communicators:
      slack:
        kind: slack
        app_id: A01234567
    ```
  </Tab>
</Tabs>

Save and restart Friday. You'll still need to set Slack's **Request URL** to `<tunnel>/platform/slack` and subscribe to `message.im` and `app_mention` events — the manifest above does this in one shot.