# tool_slack A RocketRide tool node that lets an AI agent act on a Slack workspace. ## What it does Gives an agent the core Slack operations: post messages to channels or threads, list public channels, read channel history, and verify the connection. Useful for agents that announce results, notify a team channel, or read recent discussion before answering. Uses the official **slack_sdk** package — `WebClient` for the Slack Web API in bot-token mode, `WebhookClient` in incoming-webhook mode. API responses are stripped down to compact, agent-useful fields (channel ids and names, message `ts`/`user`/`text`) instead of raw Slack JSON. Exactly one of the two auth modes must be configured; the pipeline fails to start with both or neither: | Mode | Configured with | Tools available | |---|---|---| | **Bot token** | `token` (starts with `xoxb-`) | all four tools | | **Incoming webhook** | `webhookUrl` | `message_post` only | --- ## Configuration | Field | Type | Description | |---|---|---| | `token` | string | Default empty. Bot User OAuth Token from the app's **OAuth & Permissions** page. Needs `chat:write` to post, `channels:read` to list channels, and `channels:history` to read history. Leave empty when using a webhook URL. | | `webhookUrl` | string | Default empty. Slack incoming-webhook URL for zero-scope, post-only setups. Messages always go to the channel the webhook was created for. Configure either this or a bot token, not both. | Both fields are secure (masked in the UI). Reference secrets with the engine's environment substitution instead of pasting literals, e.g. `"token": "${ROCKETRIDE_SLACK_TOKEN}"`. When **neither** field is set, the node falls back to the `ROCKETRIDE_SLACK_TOKEN` / `ROCKETRIDE_SLACK_WEBHOOK_URL` environment variables; explicitly configured values always win, so a stray environment variable can never override the configured mode. --- ## Available tools | Tool | Description | |---|---| | `check_connection` | Verify the credentials via `auth.test`. Returns the workspace (`team`, `team_id`, `url`) and bot identity (`user`, `user_id`, `bot_id`). | | `message_post` | Post a message via `chat.postMessage`. `text` is required; `channel` is required in token mode. Optional `thread_ts` replies in a thread; `unfurl_links` (default `true`) controls link previews. Returns `channel`/`ts` (plus `thread_ts` when replying in a thread). | | `channels_list` | List **public** channels via `conversations.list`. `limit` 1–1000 (default 200); cursor pagination is handled internally with a hard cap of 1000 channels. Returns `id`, `name`, `is_private`, `is_archived`, and `num_members` per channel. | | `channel_history` | Read recent messages via `conversations.history`, newest first. `channel` is required (the bot must be a member); `limit` 1–200 (default 50); optional `oldest`/`latest` timestamps bound the window. Returns `ts`, `user`, and `text` (plus `thread_ts` for threaded messages) per message. | Channel parameters accept a channel ID (e.g. `C0123ABCDEF`) or a name (e.g. `#general`). If a call fails with `channel_not_found` for a name, resolve the ID with `channels_list` first — some Slack endpoints only accept IDs. ### Webhook mode With `webhookUrl` configured, only `message_post` is available. `channel` and `thread_ts` are ignored — the message always goes to the channel the webhook was created for — and the result carries an explicit `note` saying so. The other three tools fail with a `SlackBadRequestError` explaining that they require a bot token. --- ## Authentication ### Bot token 1. Create an app at [api.slack.com/apps](https://api.slack.com/apps) (**From scratch**). 2. Under **OAuth & Permissions → Scopes → Bot Token Scopes**, add the scopes below. 3. **Install App** to the workspace and copy the **Bot User OAuth Token** (starts with `xoxb-`) into `token`. 4. Invite the bot to every channel it should post to or read: `/invite @your-bot`. | Tool | Required scope | |---|---| | `message_post` | `chat:write` | | `channels_list` | `channels:read` | | `channel_history` | `channels:history` | | `check_connection` | none (any valid bot token) | A missing scope surfaces as a `SlackMissingScopeError` naming the exact scope to add. The node only lists public channels; reading a channel's history requires the bot to be a member of it. ### Incoming webhook For post-only setups without granting any OAuth scopes: in the app, open **Incoming Webhooks**, activate them, click **Add New Webhook to Workspace**, pick the target channel, and copy the generated URL into `webhookUrl`. Treat the webhook URL itself as a secret — anyone holding it can post to the channel. --- ## Errors Failures are raised as a typed hierarchy (all subclasses of `SlackError`), named so retry/circuit-breaker heuristics can classify them: | Error | Raised on | Retryable | |---|---|---| | `SlackAuthenticationError` | `invalid_auth`, `not_authed`, `account_inactive`, `token_revoked`, `token_expired`; webhook `invalid_token`/`forbidden` | no — fix the token or webhook URL | | `SlackMissingScopeError` | `missing_scope` — the message names the missing OAuth scope from Slack's `needed` field | no — add the scope and reinstall the app | | `SlackRateLimitError` | `ratelimited` / HTTP 429 — `retry_after` carries the wait in seconds from Slack's `Retry-After` header | yes, after `retry_after` | | `SlackBadRequestError` | invalid requests, e.g. `channel_not_found` (check the ID or name), `not_in_channel` (invite the bot), `is_archived`; also any non-post tool in webhook mode | no — fix the request | | `SlackServerError` | `internal_error`, `service_unavailable`, `fatal_error`, HTTP 5xx, and unexpected failures | yes | Error messages are built exclusively from Slack's structured response fields (error code, `needed` scope, `Retry-After` header) — never from raw exception text — so the configured token or webhook URL can never leak into an error or log message. --- ## Example [`examples/slack-agent.pipe`](../../../../examples/slack-agent.pipe) wires `chat → agent_rocketride → response` with this node attached on the tool channel, so the agent can post its answers to a channel, list channels, and read recent history. --- ## Running the tests ```bash # Self-contained unit tests (no credentials, no network) pytest nodes/test/tool_slack/test_slack.py -v ``` The dynamic services test (part of `builder nodes:test-full`) needs no credentials: in mock mode (`ROCKETRIDE_MOCK`) the test framework injects a placeholder token and the canonical mock under `nodes/test/mocks/slack_sdk/` answers the API calls. With a real `ROCKETRIDE_SLACK_TOKEN` exported and mock mode off, the same test runs against the live Slack API via the node's env-var fallback. --- ## Schema | Field | Type | Description | Default | |---|---|---|---| | `slack.token` | `string` | **Bot User OAuth Token**
Slack bot token (starts with xoxb-) from your app's OAuth & Permissions page. Needs chat:write to post, channels:read to list channels, and channels:history to read history. Leave empty when using a webhook URL. | `""` | | `slack.webhookUrl` | `string` | **Incoming Webhook URL**
Slack incoming-webhook URL for zero-scope setups. Enables ONLY message_post, and messages always go to the channel the webhook was created for. Configure either this or a bot token, not both. | `""` | ## Dependencies - `slack_sdk` `>=3.27.0,<4.0.0` ## Source [ View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_slack)