Slack - Mirage

Credentials

1. Create a Slack App

Go to https://api.slack.com/apps
Create New App -> From scratch
Name it (e.g., “Mirage”) and select your workspace

2. Configure Bot Permissions

OAuth & Permissions in the left sidebar
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

Install App in the left sidebar -> Install to Workspace
Authorize the requested permissions
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:

Add search:read under User Token Scopes.
Reinstall or reauthorize the app.
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

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