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

# Slack

> Set up a Slack Bot Token for the Slack resource.

## Credentials

### 1. Create a Slack App

1. Go to [https://api.slack.com/apps](https://api.slack.com/apps)
2. **Create New App** -> **From scratch**
3. Name it (e.g., "Mirage") and select your workspace

### 2. Configure Bot Permissions

1. **OAuth & Permissions** in the left sidebar
2. Under **Bot Token Scopes**, add:
   * `channels:history` - read messages in public channels
   * `channels:read` - list public channels
   * `groups:history` - read messages in private channels (optional)
   * `groups:read` - list private channels (optional)
   * `chat:write` - send messages (for write mode)

### 3. Install to Workspace

1. **Install App** in the left sidebar -> **Install to Workspace**
2. Authorize the requested permissions
3. Copy the **Bot User OAuth Token** (`xoxb-...`)

### 4. Optional: Enable Workspace Search

Slack's `search.messages` API does not accept bot tokens. To use `slack search` or workspace-level search push-down:

1. Add `search:read` under **User Token Scopes**.
2. Reinstall or reauthorize the app.
3. Copy the resulting **User OAuth Token** (`xoxp-...`).

Keep using the bot token for normal reads and writes. Mirage uses the optional user token only for Slack search endpoints.

### 5. Set Environment Variables

```bash theme={null}
# .env.development
SLACK_BOT_TOKEN=xoxb-xxxx...
SLACK_USER_TOKEN=xoxp-xxxx...  # optional, only needed for workspace search
```

### 6. Invite the Bot

The bot must be invited to channels it needs to read:

```
/invite @Mirage
```

For Python configuration, see the [Python Slack Setup](/python/setup/slack) guide.