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

# Connect Slack

> Set up the Slack transport so ShoulderTap asks experts by direct message and captures their replies through the Slack Events API.

The Slack transport is how ShoulderTap reaches real experts in production. It sends each ask as a direct message from a Slack app you install, and captures the expert's reply through the Events API. The console transport is enough for local testing; switch to Slack when you're ready to ask real people.

<Info>
  ShoulderTap only ever DMs experts directly. It does not read channels, post in channels, or index message history — it sends one well-formed DM per ask and listens for the reply in that DM thread.
</Info>

## Set up the Slack app

<Steps>
  <Step title="Create the app from the manifest">
    Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From an app manifest**, and paste in the `slack/manifest.yaml` shipped in the repository. The manifest requests exactly the scopes ShoulderTap needs: `chat:write`, `im:history`, `im:write`, and `users:read`, plus the `message.im` event.
  </Step>

  <Step title="Copy the credentials into .env">
    From the app's settings, copy the **Bot User OAuth Token** into `SLACK_BOT_TOKEN` and the **Signing Secret** into `SLACK_SIGNING_SECRET` in your `.env` file (copied from `.env.example`). `.env` is gitignored and never committed.

    ```bash .env theme={null}
    SLACK_BOT_TOKEN=xoxb-...
    SLACK_SIGNING_SECRET=...
    ```

    These variable names are referenced by `slack.bot_token_env` and `slack.signing_secret_env` in `shouldertap.yaml`.
  </Step>

  <Step title="Point Event Subscriptions at your server">
    In the app's **Event Subscriptions**, set the request URL to your server's Slack endpoint:

    ```
    https://<your-host>/api/v1/slack/events
    ```

    Slack signs these requests itself, so this route is exempt from bearer-token auth. Your server must be reachable from Slack (use a tunnel like ngrok for local development).
  </Step>

  <Step title="Run with the Slack transport">
    ```bash theme={null}
    shtap serve --transport slack
    ```

    ShoulderTap now DMs experts through Slack instead of printing to the terminal.
  </Step>
</Steps>

## Expert IDs

With the Slack transport, each expert's `id` in `shouldertap.yaml` must be their **Slack user ID** (for example `U0123ABC`), since that's the channel ShoulderTap DMs. This is the same registry described in [Experts and routing](/run/experts) — only the meaning of `id` becomes concrete.

## What experts see

The expert receives a direct message with the full [safety-promise structure](/run/experts#the-outbound-ask): self-identification, why it's being asked, the question, effort framing, the attribution promise, and the `mute` / `skip` opt-outs. They reply in the DM thread; ShoulderTap captures that reply, structures it into a proposal, and sends it to the approval queue.

Replies that aren't in a direct-message thread, messages from bots, and message edits are ignored — only a human's direct reply is captured.