Slack

The Slack adapter lets a heypi agent receive Slack messages, stream replies, upload generated files, and render approval buttons.

Slack decides what your app receives before heypi sees an event. Configure Slack scopes, event subscriptions, interactivity, and channel membership first; then use heypi's allow config to filter delivered events.

For a runnable example, see examples/slack-devops.

Modes

The default HTTP route is /slack/{name}/events. With the default adapter name, use this URL; the repeated slack segment is expected because the adapter name also defaults to slack:

https://<host>/slack/slack/events

With slack({ name: "ops", mode: "http", ... }), use:

https://<host>/slack/ops/events

Options

slack() accepts the shared options documented in Adapters, plus Slack-specific options below.

Actor access is users OR groups. Channel access is separate. With:

allow: { channels: ["C1"], users: ["U1"], groups: ["S1"] }

U1 or members of S1 can use the bot in C1. DMs require allow.dms.

Bot messages are rejected by default. To accept fixture or integration messages from another Slack app, configure allow.bots:

allow: { channels: ["C1"], bots: ["B_TEST"] }

Use bots: true to accept messages from all other Slack bots/apps. This adapter's own Slack bot/app messages are always dropped, even when allow.bots is true or includes its own IDs. Allowed bot messages still have to pass the channel, DM, and trigger rules.

allow.bots only grants input access. Bot actors cannot list, approve, deny, or revoke approvals through the zero-config fallback. To let a trusted bot resolve approvals, list its bot user ID in permissions.approvers or permissions.admins.

Setup

Manifest setup

Generate a starter Slack manifest for HTTP mode:

heypi slack manifest --mode http --url https://<host>/slack/slack/events

For Socket Mode, generate the Socket Mode manifest:

heypi slack manifest --mode socket

Import the manifest into Slack, then review scopes, events, interactivity, and the /heypi slash command for your workspace. Socket Mode still needs an app-level token with connections:write.

Slack slash command names are workspace-global. If you run multiple heypi Slack apps in one workspace, set a unique command name in both the manifest and adapter config.

Slack slash-command payloads include a short-lived trigger_id for immediate Slack interactions. heypi uses it only to derive a non-reversible internal event id for retry dedupe. The raw trigger_id is not stored in message data or trace ids.

Typed controls use /heypi subcommands:

/heypi approvals
/heypi bypasses
/heypi approve <approval-id>
/heypi deny <approval-id>
/heypi status [run-or-call-id]
/heypi cancel <turn-id-or-trace>
/heypi revoke <bypass-id>
/heypi bash <command>

Manual setup

1. Create a Slack app at https://api.slack.com/apps.
2. Add a bot user.
3. Add bot scopes from the table below.
4. Subscribe to bot events from the table below.
5. Enable Interactivity for approval buttons and set the HTTP URL when using HTTP mode.
6. Add the configured slash command, /heypi by default.
7. Install the app into your workspace.
8. Invite the bot to channels where it should respond.
9. Copy the required tokens or secrets into your environment.

Typical bot scopes:

Add private-channel scopes only if the bot must read private channels.

Typical bot events:

Config

Socket mode

createHeypi({
  state: { root: "./state" },
  adapters: [
    slack({
      mode: "socket",
      allow: { channels: ["C123"], bots: ["B_TEST"], dms: true },
      trigger: "mention",
      threadTrigger: "message",
    }),
  ],
});

HTTP mode

createHeypi({
  state: { root: "./state" },
  http: { port: Number(process.env.PORT ?? 3000) },
  adapters: [
    slack({
      mode: "http",
      allow: { channels: ["C123"], dms: true },
      trigger: "mention",
      threadTrigger: "message",
    }),
  ],
});

Slack HTTP mode needs a stable public URL for Slack Event Subscriptions, Interactivity, and slash commands. Use port: 0 only for local Socket Mode/admin setups, not for Slack HTTP mode unless a tunnel or reverse proxy provides a stable URL.

Common environment variables:

For app-wide config such as http, state, runtime, and agent, see Configuration.

CLI