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

# Slack

> Talk to your agent in Slack channels and direct messages

Connect IronClaw to a Slack workspace so your agent can read and reply to messages in
channels and DMs.

## Prerequisites

* A Slack workspace where you can install apps
* An IronClaw instance reachable from Slack over HTTPS

***

## Setup

<Steps>
  <Step title="Create a Slack app">
    Create an app at [api.slack.com/apps](https://api.slack.com/apps). The fastest route is
    **From an app manifest** — paste the [manifest below](#app-manifest), which sets the
    scopes, events, and redirect URL in one step. Replace `example.com` with your own host
    first.

    If you build the app from scratch instead, configure **OAuth & Permissions**, **Event
    Subscriptions**, and the redirect URL to match that manifest.

    Once created, install the app to your workspace and copy the bot token from **OAuth &
    Permissions**, and the signing secret from **Basic Information**. IronClaw uses the signing
    secret to verify that incoming requests really came from Slack.
  </Step>

  <Step title="Start IronClaw">
    ```bash theme={null}
    ironclaw serve
    ```
  </Step>

  <Step title="Connect the channel">
    In the [web interface](/using/webui), open **Extensions**, switch to the **Channels** tab,
    and scroll to the **bottom of the Built-in section**. Use **Configure** on the Slack card
    and provide the app id, bot token, and signing secret. They are written to the encrypted
    secret store.

    <Warning>
      Extensions opens on the **Registry** tab, which is not where channels are connected, and
      the Slack card sits below the web and terminal rows on the Channels tab. If you can't find
      it, you're probably on the wrong tab or haven't scrolled.
    </Warning>

    <Note>
      Asking the agent to "connect Slack" will not work. It can install and use Slack *tools*
      once the channel is connected, but making the connection is an operator action that stays
      in the web interface. The agent may reply that it can't help.
    </Note>
  </Step>

  <Step title="Point Slack at your instance">
    Back in your Slack app, confirm **Event Subscriptions** points at your instance:

    ```
    https://your-host/webhooks/slack/events
    ```

    Slack sends a verification challenge to that URL, so IronClaw must already be running and
    reachable when you save it. Reinstall the app if Slack asks you to.
  </Step>

  <Step title="Talk to it">
    Invite the bot to a channel and mention it, or send it a direct message.
  </Step>
</Steps>

***

## URLs Slack Needs

Both are served by `ironclaw serve`, so they use whatever host and port your instance is
reachable on. Replace `your-host` and use HTTPS — Slack will not deliver to a plain-HTTP
or self-signed endpoint.

| Slack setting                      | URL                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------- |
| Event Subscriptions → Request URL  | `https://your-host/webhooks/slack/events`                                 |
| OAuth & Permissions → Redirect URL | `https://your-host/api/reborn/product-auth/oauth/slack_personal/callback` |

The redirect URL is used for per-user ("personal") Slack authorization. Tell IronClaw the
same value so the two agree:

```bash theme={null}
export IRONCLAW_REBORN_SLACK_PERSONAL_OAUTH_REDIRECT_URI=https://your-host/api/reborn/product-auth/oauth/slack_personal/callback
```

<Warning>
  The redirect URL must match **exactly** on both sides, including scheme, host, port, and
  path. Slack rejects the authorization with a redirect-URI mismatch if it differs by even a
  trailing slash. The path is `/api/reborn/product-auth/oauth/slack_personal/callback` — a
  shortened form like `/oauth/slack_personal/callback` is not served and will 404.
</Warning>

For a local instance the values are `http://127.0.0.1:3000/...`, but Slack cannot reach
loopback, so events only work once the instance is reachable from the internet.

***

## App Manifest

Create the app with **From an app manifest** and paste this, replacing `example.com` with
your host. It sets the scopes, bot events, and redirect URL that the steps above describe.

```json theme={null}
{
  "display_information": {
    "name": "IronClaw"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "IronClaw",
      "always_online": true
    }
  },
  "oauth_config": {
    "redirect_urls": [
      "https://example.com/api/reborn/product-auth/oauth/slack_personal/callback"
    ],
    "scopes": {
      "user": [
        "search:read",
        "channels:history",
        "groups:history",
        "im:history",
        "mpim:history",
        "channels:read",
        "groups:read",
        "im:read",
        "mpim:read",
        "users:read",
        "chat:write"
      ],
      "bot": [
        "channels:history",
        "app_mentions:read",
        "chat:write",
        "im:history",
        "im:write",
        "files:read",
        "groups:history",
        "mpim:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://example.com/webhooks/slack/events",
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim"
      ]
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}
```

<Note>
  This is a starting point, not a minimum. The `user` scopes exist for per-user
  authorization — searching and posting as the person rather than as the bot. If you only
  want the bot to participate in channels, you can drop the `user` block and the redirect
  URL with it.
</Note>

Slack validates the request URL when you save the manifest, so start IronClaw before
creating the app.

***

## Configuration

Slack settings live under `[slack]` in your configuration file. Set them through the web
interface rather than by hand — the tokens belong in the secret store, and the file only
names the variables that hold them.

```toml theme={null}
[slack]
enabled = true
```

| Key                        | Purpose                                         |
| -------------------------- | ----------------------------------------------- |
| `slack.enabled`            | Turn the Slack route on                         |
| `slack.api_app_id`         | Your Slack app id                               |
| `slack.bot_token_env`      | Name of the variable holding the bot token      |
| `slack.signing_secret_env` | Name of the variable holding the signing secret |
| `slack.team_id`            | Workspace the app is installed in               |
| `slack.channel_routes`     | Which conversations map to which agent scope    |

Check what's currently set:

```bash theme={null}
ironclaw config list | grep slack
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Slack can't verify the request URL">
    IronClaw has to be running and publicly reachable over HTTPS before you save the URL.
    Confirm the instance answers from outside your network, and that you used the exact
    `/webhooks/slack/events` path.
  </Accordion>

  <Accordion title="Slack rejects authorization with a redirect-URI mismatch">
    The redirect URL in the Slack app and `IRONCLAW_REBORN_SLACK_PERSONAL_OAUTH_REDIRECT_URI`
    must match character for character. Check the scheme, the port, and that the path is the
    full `/api/reborn/product-auth/oauth/slack_personal/callback`.
  </Accordion>

  <Accordion title="The bot doesn't respond in a channel">
    Invite the bot to that channel, and make sure you subscribed to the matching message
    event. A bot only sees conversations it belongs to.
  </Accordion>

  <Accordion title="Requests are rejected">
    A wrong or missing signing secret makes IronClaw reject every incoming request. Re-enter
    it through the setup flow, then restart the server.
  </Accordion>

  <Accordion title="I can't find where to configure Slack">
    Open **Extensions**, switch from **Registry** to the **Channels** tab, and scroll to the
    bottom of the Built-in section. The Slack card is below the web and terminal channel rows.
  </Accordion>
</AccordionGroup>