> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

# Slack

Status: production-ready for DMs + channels via Slack app integrations. Default mode is Socket Mode; HTTP Events API mode is also supported.

> [card] [Pairing](https://agdiai-597e782f.mintlify.site/channels/pairing.md)
>
> Slack DMs default to pairing mode.

> [card] [Slash commands](https://agdiai-597e782f.mintlify.site/tools/slash-commands.md)
>
> Native command behavior and command catalog.

> [card] [Channel troubleshooting](https://agdiai-597e782f.mintlify.site/channels/troubleshooting.md)
>
> Cross-channel diagnostics and repair playbooks.

## Quick setup

> [tab] Socket Mode (default)
>
> **1. Create Slack app and tokens**
>
> In Slack app settings:
>
> * enable **Socket Mode**
> * create **App Token** (`xapp-...`) with `connections:write`
> * install app and copy **Bot Token** (`xoxb-...`)
>
> **2. Configure Agdi**
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   channels: {
>     slack: {
>       enabled: true,
>       mode: "socket",
>       appToken: "xapp-...",
>       botToken: "xoxb-...",
>     },
>   },
> }
> ```
>
> Env fallback (default account only):
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> SLACK_APP_TOKEN=xapp-...
> SLACK_BOT_TOKEN=xoxb-...
> ```
>
> **3. Subscribe app events**
>
> Subscribe bot events for:
>
> * `app_mention`
> * `message.channels`, `message.groups`, `message.im`, `message.mpim`
> * `reaction_added`, `reaction_removed`
> * `member_joined_channel`, `member_left_channel`
> * `channel_rename`
> * `pin_added`, `pin_removed`
>
> Also enable App Home **Messages Tab** for DMs.
>
> **4. Start gateway**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi gateway
> ```

> [tab] HTTP Events API mode
>
> **1. Configure Slack app for HTTP**
>
> * set mode to HTTP (`channels.slack.mode="http"`)
> * copy Slack **Signing Secret**
> * set Event Subscriptions + Interactivity + Slash command Request URL to the same webhook path (default `/slack/events`)
>
> **2. Configure Agdi HTTP mode**
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   channels: {
>     slack: {
>       enabled: true,
>       mode: "http",
>       botToken: "xoxb-...",
>       signingSecret: "your-signing-secret",
>       webhookPath: "/slack/events",
>     },
>   },
> }
> ```
>
> **3. Use unique webhook paths for multi-account HTTP**
>
> Per-account HTTP mode is supported.
>
> Give each account a distinct `webhookPath` so registrations do not collide.

## Token model

* `botToken` + `appToken` are required for Socket Mode.
* HTTP mode requires `botToken` + `signingSecret`.
* Config tokens override env fallback.
* `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
* `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
* Optional: add `chat:write.customize` if you want outgoing messages to use the active agent identity (custom `username` and icon). `icon_emoji` uses `:emoji_name:` syntax.

> [!TIP]
>
> For actions/directory reads, user token can be preferred when configured. For writes, bot token remains preferred; user-token writes are only allowed when `userTokenReadOnly: false` and bot token is unavailable.

## Access control and routing

> [tab] DM policy
>
> `channels.slack.dmPolicy` controls DM access (legacy: `channels.slack.dm.policy`):
>
> * `pairing` (default)
> * `allowlist`
> * `open` (requires `channels.slack.allowFrom` to include `"*"`; legacy: `channels.slack.dm.allowFrom`)
> * `disabled`
>
> DM flags:
>
> * `dm.enabled` (default true)
> * `channels.slack.allowFrom` (preferred)
> * `dm.allowFrom` (legacy)
> * `dm.groupEnabled` (group DMs default false)
> * `dm.groupChannels` (optional MPIM allowlist)
>
> Multi-account precedence:
>
> * `channels.slack.accounts.default.allowFrom` applies only to the `default` account.
> * Named accounts inherit `channels.slack.allowFrom` when their own `allowFrom` is unset.
> * Named accounts do not inherit `channels.slack.accounts.default.allowFrom`.
>
> Pairing in DMs uses `agdi pairing approve slack <code>`.

> [tab] Channel policy
>
> `channels.slack.groupPolicy` controls channel handling:
>
> * `open`
> * `allowlist`
> * `disabled`
>
> Channel allowlist lives under `channels.slack.channels` and should use stable channel IDs.
>
> Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
>
> Name/ID resolution:
>
> * channel allowlist entries and DM allowlist entries are resolved at startup when token access allows
> * unresolved channel-name entries are kept as configured but ignored for routing by default
> * inbound authorization and channel routing are ID-first by default; direct username/slug matching requires `channels.slack.dangerouslyAllowNameMatching: true`

> [tab] Mentions and channel users
>
> Channel messages are mention-gated by default.
>
> Mention sources:
>
> * explicit app mention (`<@botId>`)
> * mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
> * implicit reply-to-bot thread behavior
>
> Per-channel controls (`channels.slack.channels.<id>`; names only via startup resolution or `dangerouslyAllowNameMatching`):
>
> * `requireMention`
> * `users` (allowlist)
> * `allowBots`
> * `skills`
> * `systemPrompt`
> * `tools`, `toolsBySender`
> * `toolsBySender` key format: `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
>   (legacy unprefixed keys still map to `id:` only)

## Commands and slash behavior

* Native command auto-mode is **off** for Slack (`commands.native: "auto"` does not enable Slack native commands).
* Enable native Slack command handlers with `channels.slack.commands.native: true` (or global `commands.native: true`).
* When native commands are enabled, register matching slash commands in Slack (`/<command>` names), with one exception:
  * register `/agentstatus` for the status command (Slack reserves `/status`)
* If native commands are not enabled, you can run a single configured slash command via `channels.slack.slashCommand`.
* Native arg menus now adapt their rendering strategy:
  * up to 5 options: button blocks
  * 6-100 options: static select menu
  * more than 100 options: external select with async option filtering when interactivity options handlers are available
  * if encoded option values exceed Slack limits, the flow falls back to buttons
* For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.

## Interactive replies

Slack can render agent-authored interactive reply controls, but this feature is disabled by default.

Enable it globally:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    slack: {
      capabilities: {
        interactiveReplies: true,
      },
    },
  },
}
```

Or enable it for one Slack account only:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    slack: {
      accounts: {
        ops: {
          capabilities: {
            interactiveReplies: true,
          },
        },
      },
    },
  },
}
```

When enabled, agents can emit Slack-only reply directives:

* `[[slack_buttons: Approve:approve, Reject:reject]]`
* `[[slack_select: Choose a target | Canary:canary, Production:production]]`

These directives compile into Slack Block Kit and route clicks or selections back through the existing Slack interaction event path.

Notes:

* This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
* The interactive callback values are Agdi-generated opaque tokens, not raw agent-authored values.
* If generated interactive blocks would exceed Slack Block Kit limits, Agdi falls back to the original text reply instead of sending an invalid blocks payload.

Default slash command settings:

* `enabled: false`
* `name: "agdi"`
* `sessionPrefix: "slack:slash"`
* `ephemeral: true`

Slash sessions use isolated keys:

* `agent:<agentId>:slack:slash:<userId>`

and still route command execution against the target conversation session (`CommandTargetSessionKey`).

## Threading, sessions, and reply tags

* DMs route as `direct`; channels as `channel`; MPIMs as `group`.
* With default `session.dmScope=main`, Slack DMs collapse to agent main session.
* Channel sessions: `agent:<agentId>:slack:channel:<channelId>`.
* Thread replies can create thread session suffixes (`:thread:<threadTs>`) when applicable.
* `channels.slack.thread.historyScope` default is `thread`; `thread.inheritParent` default is `false`.
* `channels.slack.thread.initialHistoryLimit` controls how many existing thread messages are fetched when a new thread session starts (default `20`; set `0` to disable).

Reply threading controls:

* `channels.slack.replyToMode`: `off|first|all` (default `off`)
* `channels.slack.replyToModeByChatType`: per `direct|group|channel`
* legacy fallback for direct chats: `channels.slack.dm.replyToMode`

Manual reply tags are supported:

* `[[reply_to_current]]`
* `[[reply_to:<id>]]`

Note: `replyToMode="off"` disables **all** reply threading in Slack, including explicit `[[reply_to_*]]` tags. This differs from Telegram, where explicit tags are still honored in `"off"` mode. The difference reflects the platform threading models: Slack threads hide messages from the channel, while Telegram replies remain visible in the main chat flow.

## Media, chunking, and delivery

> [accordion] Inbound attachments
>
> Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit.
>
> Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.

> [accordion] Outbound text and files
>
> * text chunks use `channels.slack.textChunkLimit` (default 4000)
> * `channels.slack.chunkMode="newline"` enables paragraph-first splitting
> * file sends use Slack upload APIs and can include thread replies (`thread_ts`)
> * outbound media cap follows `channels.slack.mediaMaxMb` when configured; otherwise channel sends use MIME-kind defaults from media pipeline

> [accordion] Delivery targets
>
> Preferred explicit targets:
>
> * `user:<id>` for DMs
> * `channel:<id>` for channels
>
> Slack DMs are opened via Slack conversation APIs when sending to user targets.

## Actions and gates

Slack actions are controlled by `channels.slack.actions.*`.

Available action groups in current Slack tooling:

| Group | Default |
| - | - |
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| memberInfo | enabled |
| emojiList | enabled |

## Events and operational behavior

* Message edits/deletes/thread broadcasts are mapped into system events.
* Reaction add/remove events are mapped into system events.
* Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
* Assistant thread status updates (for "is typing..." indicators in threads) use `assistant.threads.setStatus` and require bot scope `assistant:write`.
* `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
* Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
* Block actions and modal interactions emit structured `Slack interaction: ...` system events with rich payload fields:
  * block actions: selected values, labels, picker values, and `workflow_*` metadata
  * modal `view_submission` and `view_closed` events with routed channel metadata and form inputs

## Ack reactions

`ackReaction` sends an acknowledgement emoji while Agdi is processing an inbound message.

Resolution order:

* `channels.slack.accounts.<accountId>.ackReaction`
* `channels.slack.ackReaction`
* `messages.ackReaction`
* agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")

Notes:

* Slack expects shortcodes (for example `"eyes"`).
* Use `""` to disable the reaction for the Slack account or globally.

## Typing reaction fallback

`typingReaction` adds a temporary reaction to the inbound Slack message while Agdi is processing a reply, then removes it when the run finishes. This is a useful fallback when Slack native assistant typing is unavailable, especially in DMs.

Resolution order:

* `channels.slack.accounts.<accountId>.typingReaction`
* `channels.slack.typingReaction`

Notes:

* Slack expects shortcodes (for example `"hourglass_flowing_sand"`).
* The reaction is best-effort and cleanup is attempted automatically after the reply or failure path completes.

## Manifest and scope checklist

> [accordion] Slack app manifest example
>
> ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   "display_information": {
>     "name": "Agdi",
>     "description": "Slack connector for Agdi"
>   },
>   "features": {
>     "bot_user": {
>       "display_name": "Agdi",
>       "always_online": false
>     },
>     "app_home": {
>       "messages_tab_enabled": true,
>       "messages_tab_read_only_enabled": false
>     },
>     "slash_commands": [
>       {
>         "command": "/agdi",
>         "description": "Send a message to Agdi",
>         "should_escape": false
>       }
>     ]
>   },
>   "oauth_config": {
>     "scopes": {
>       "bot": [
>         "chat:write",
>         "channels:history",
>         "channels:read",
>         "groups:history",
>         "im:history",
>         "im:read",
>         "im:write",
>         "mpim:history",
>         "mpim:read",
>         "mpim:write",
>         "users:read",
>         "app_mentions:read",
>         "assistant:write",
>         "reactions:read",
>         "reactions:write",
>         "pins:read",
>         "pins:write",
>         "emoji:read",
>         "commands",
>         "files:read",
>         "files:write"
>       ]
>     }
>   },
>   "settings": {
>     "socket_mode_enabled": true,
>     "event_subscriptions": {
>       "bot_events": [
>         "app_mention",
>         "message.channels",
>         "message.groups",
>         "message.im",
>         "message.mpim",
>         "reaction_added",
>         "reaction_removed",
>         "member_joined_channel",
>         "member_left_channel",
>         "channel_rename",
>         "pin_added",
>         "pin_removed"
>       ]
>     }
>   }
> }
> ```

> [accordion] Optional user-token scopes (read operations)
>
> If you configure `channels.slack.userToken`, typical read scopes are:
>
> * `channels:history`, `groups:history`, `im:history`, `mpim:history`
> * `channels:read`, `groups:read`, `im:read`, `mpim:read`
> * `users:read`
> * `reactions:read`
> * `pins:read`
> * `emoji:read`
> * `search:read` (if you depend on Slack search reads)

## Troubleshooting

> [accordion] No replies in channels
>
> Check, in order:
>
> * `groupPolicy`
> * channel allowlist (`channels.slack.channels`)
> * `requireMention`
> * per-channel `users` allowlist
>
> Useful commands:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi channels status --probe
> agdi logs --follow
> agdi doctor
> ```

> [accordion] DM messages ignored
>
> Check:
>
> * `channels.slack.dm.enabled`
> * `channels.slack.dmPolicy` (or legacy `channels.slack.dm.policy`)
> * pairing approvals / allowlist entries
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi pairing list slack
> ```

> [accordion] Socket mode not connecting
>
> Validate bot + app tokens and Socket Mode enablement in Slack app settings.

> [accordion] HTTP mode not receiving events
>
> Validate:
>
> * signing secret
> * webhook path
> * Slack Request URLs (Events + Interactivity + Slash Commands)
> * unique `webhookPath` per HTTP account

> [accordion] Native/slash commands not firing
>
> Verify whether you intended:
>
> * native command mode (`channels.slack.commands.native: true`) with matching slash commands registered in Slack
> * or single slash command mode (`channels.slack.slashCommand.enabled: true`)
>
> Also check `commands.useAccessGroups` and channel/user allowlists.

## Text streaming

Agdi supports Slack native text streaming via the Agents and AI Apps API.

`channels.slack.streaming` controls live preview behavior:

* `off`: disable live preview streaming.
* `partial` (default): replace preview text with the latest partial output.
* `block`: append chunked preview updates.
* `progress`: show progress status text while generating, then send final text.

`channels.slack.nativeStreaming` controls Slack's native streaming API (`chat.startStream` / `chat.appendStream` / `chat.stopStream`) when `streaming` is `partial` (default: `true`).

Disable native Slack streaming (keep draft preview behavior):

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
channels:
  slack:
    streaming: partial
    nativeStreaming: false
```

Legacy keys:

* `channels.slack.streamMode` (`replace | status_final | append`) is auto-migrated to `channels.slack.streaming`.
* boolean `channels.slack.streaming` is auto-migrated to `channels.slack.nativeStreaming`.

### Requirements

1. Enable **Agents and AI Apps** in your Slack app settings.
2. Ensure the app has the `assistant:write` scope.
3. A reply thread must be available for that message. Thread selection still follows `replyToMode`.

### Behavior

* First text chunk starts a stream (`chat.startStream`).
* Later text chunks append to the same stream (`chat.appendStream`).
* End of reply finalizes stream (`chat.stopStream`).
* Media and non-text payloads fall back to normal delivery.
* If streaming fails mid-reply, Agdi falls back to normal delivery for remaining payloads.

## Configuration reference pointers

Primary reference:

* [Configuration reference - Slack](https://agdiai-597e782f.mintlify.site/gateway/configuration-reference.md#slack)

  High-signal Slack fields:

  * mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
  * DM access: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
  * compatibility toggle: `dangerouslyAllowNameMatching` (break-glass; keep off unless needed)
  * channel access: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
  * threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
  * delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
  * ops/features: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`

## Related

* [Pairing](https://agdiai-597e782f.mintlify.site/channels/pairing.md)
* [Channel routing](https://agdiai-597e782f.mintlify.site/channels/channel-routing.md)
* [Troubleshooting](https://agdiai-597e782f.mintlify.site/channels/troubleshooting.md)
* [Configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md)
* [Slash commands](https://agdiai-597e782f.mintlify.site/tools/slash-commands.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.