Heypi’s Slack adapter connects your agent to Slack workspaces using either Socket Mode (a persistent WebSocket connection ideal for local development) or HTTP Mode (a standard webhook receiver for production deployments). Both modes are powered by Slack Bolt, and the same access control, streaming, and approval features apply to either.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt
Use this file to discover all available pages before exploring further.
Create a Slack App
Open the Slack API dashboard
Go to https://api.slack.com/apps and click Create New App.
Socket Mode vs HTTP Mode
- Socket Mode (local dev)
- HTTP Mode (production)
Socket Mode connects to Slack over a persistent WebSocket. No public URL is required, making it ideal for local development.
Create an app-level token
Under Basic Information → App-Level Tokens, create a token with the
connections:write scope. Copy the token:Access Control
Slack decides which events heypi receives through your app installation, OAuth scopes, event subscriptions, and channel membership. Heypi’sallow config filters those events after Slack delivers them — it does not replace Slack’s own delivery rules.
allow.channels applies to non-DM channels only. For private channels, invite the bot to the channel, grant groups:read, reinstall the app, and then use heypi slack channels --private to discover channel IDs.Streaming
Enable token-by-token streaming withstreaming: true, or tune the behavior with an object:
Progress Indicator
By default, heypi posts a “Working…” placeholder message in the thread (after a short delay) and reacts with 👀 on the original message while a turn is running. Customize or disable this withprogress:
Reply Placement
Control where replies land in Slack channels:CLI Commands
Use the heypi CLI to validate your setup and discover IDs:heypi slack check
Validates
SLACK_BOT_TOKEN and prints the workspace and bot identity.heypi slack channels
Lists channel IDs visible to the bot. Add
--private for private channels (requires groups:read scope).heypi slack manifest
Generates a starter Slack app manifest for HTTP mode with the correct event subscriptions and redirect URLs.
Full Example
The following is the completeexamples/slack-devops entry point — a DevOps agent with Socket Mode, streaming, access control, approval gates, and scheduled jobs:
Common Failures
invalid_auth
invalid_auth
SLACK_BOT_TOKEN is wrong, expired, or the app was reinstalled since the token was last copied. Re-copy the bot token from OAuth & Permissions and update your .env file.not_authed
not_authed
The token was not sent or was loaded from the wrong
.env file. Confirm the file path passed to --env matches where you stored the token, and that the variable name is exactly SLACK_BOT_TOKEN.No messages arriving in channels
No messages arriving in channels
Check that:
app_mentions:readandmessage.channelsscopes are both added.- The bot is invited to the channel (
/invite @yourbot). - Event Subscriptions are enabled and pointed at the correct URL (HTTP mode).
Buttons not working (approvals / cancel)
Buttons not working (approvals / cancel)
Socket Mode not connecting
Socket Mode not connecting
Verify
SLACK_APP_TOKEN starts with xapp- and has the connections:write scope. The bot token (SLACK_BOT_TOKEN) and app token (SLACK_APP_TOKEN) are different — ensure you haven’t swapped them.