diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 67ebcfe1442..217aea530bb 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -120,275 +120,6 @@ openclaw gateway -## 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. - - -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 - - - - `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 `openclaw pairing approve slack `. - - - - - `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` - - - - - 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.`; 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 (`/` 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. - -Default slash command settings: - -- `enabled: false` -- `name: "openclaw"` -- `sessionPrefix: "slack:slash"` -- `ephemeral: true` - -Slash sessions use isolated keys: - -- `agent::slack:slash:` - -and still route command execution against the target conversation session (`CommandTargetSessionKey`). - -## Interactive replies - -Slack can render agent-authored interactive reply controls, but this feature is disabled by default. - -Enable it globally: - -```json5 -{ - channels: { - slack: { - capabilities: { - interactiveReplies: true, - }, - }, - }, -} -``` - -Or enable it for one Slack account only: - -```json5 -{ - 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 OpenClaw-generated opaque tokens, not raw agent-authored values. -- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload. - -## 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::slack:channel:`. -- Thread replies can create thread session suffixes (`:thread:`) 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:]]` - -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 - - - - 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`. - - - - - - 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 - - - - Preferred explicit targets: - - - `user:` for DMs - - `channel:` 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 | - -Current Slack message actions include `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, and `emoji-list`. - -## 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. -- Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable. -- 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 OpenClaw is processing an inbound message. - -Resolution order: - -- `channels.slack.accounts..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 OpenClaw 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..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 @@ -483,6 +214,303 @@ Notes: +## 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. + + +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. + + +## 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 | + +Current Slack message actions include `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, and `emoji-list`. + +## Access control and routing + + + + `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 `openclaw pairing approve slack `. + + + + + `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` + + + + + 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.`; 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) + + + + +## 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::slack:channel:`. +- Thread replies can create thread session suffixes (`:thread:`) 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:]]` + +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. + +## Ack reactions + +`ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message. + +Resolution order: + +- `channels.slack.accounts..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. + +## Text streaming + +OpenClaw 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 +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, OpenClaw falls back to normal delivery for remaining payloads. + +## Typing reaction fallback + +`typingReaction` adds a temporary reaction to the inbound Slack message while OpenClaw 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..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. + +## Media, chunking, and delivery + + + + 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`. + + + + + - 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 + + + + Preferred explicit targets: + + - `user:` for DMs + - `channel:` for channels + + Slack DMs are opened via Slack conversation APIs when sending to user targets. + + + + +## 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 (`/` 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. + +Default slash command settings: + +- `enabled: false` +- `name: "openclaw"` +- `sessionPrefix: "slack:slash"` +- `ephemeral: true` + +Slash sessions use isolated keys: + +- `agent::slack:slash:` + +and still route command execution against the target conversation session (`CommandTargetSessionKey`). + +## Interactive replies + +Slack can render agent-authored interactive reply controls, but this feature is disabled by default. + +Enable it globally: + +```json5 +{ + channels: { + slack: { + capabilities: { + interactiveReplies: true, + }, + }, + }, +} +``` + +Or enable it for one Slack account only: + +```json5 +{ + 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 OpenClaw-generated opaque tokens, not raw agent-authored values. +- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload. + ## Exec approvals in Slack Exec approval prompts can route natively through Slack using interactive buttons and interactions, instead of falling back to the Web UI or terminal. Approver authorization is enforced: only users identified as approvers can approve or deny requests through Slack. @@ -532,6 +560,34 @@ to other chats or explicit out-of-band targets. Same-chat `/approve` also works in Slack channels and DMs that already support commands. See [Exec approvals](/tools/exec-approvals) for the full approval forwarding model. +## 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. +- Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable. +- 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 + +## Configuration reference pointers + +Primary reference: + +- [Configuration reference - Slack](/gateway/configuration-reference#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` + ## Troubleshooting @@ -591,62 +647,6 @@ openclaw pairing list slack -## Text streaming - -OpenClaw 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 -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, OpenClaw falls back to normal delivery for remaining payloads. - -## Configuration reference pointers - -Primary reference: - -- [Configuration reference - Slack](/gateway/configuration-reference#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](/channels/pairing)