slack

slack

Slack as an iii worker. Two surfaces in one worker:

1. Slack Web API as slack::* functions — agent-callable and console-callable, so anything you can do through the Slack API you can do through this worker. Needs only a bot token; plain outbound HTTPS, no ingress.
2. Harness bridge — @mention the bot in Slack and it runs a harness::send turn, streaming the reply back into the thread using Slack's native streaming (chat.startStream/appendStream/stopStream), with inline Block Kit approvals. The bridge is additive: it activates only when a public engine URL + signing secret are configured and the harness stack is connected.

Install

# API surface only:
iii worker add slack
# For the bridge, also install the harness stack and console:
iii worker add harness console

Configure

Set a bot token (and optionally a user token for search) in the console Configuration → Workers → slack, or seed it from the environment:

bot_token: "${SLACK_BOT_TOKEN}"   # xoxb-, required
user_token: "${SLACK_USER_TOKEN}" # xoxp-, optional (only slack::search::messages)
timeout_ms: 10000

Identity (workspace, team id, bot user) is not configured — it is discovered at boot via auth.test and reported by slack::config-status. All fields hot-reload through the configuration worker; no restart.

Run slack::config-status to verify the token and see the resolved identity.

Enable the bridge

signing_secret: "${SLACK_SIGNING_SECRET}"      # required for the bridge
public_base_url: "https://your-engine.example" # Slack posts events here
require_mention: true        # channels fire only on @bot mention (DMs always)
backfill_thread: true        # pull prior thread replies into the session on first mention
default_model: null          # optional; else the first model from router::models::list
functions_allow: ["slack::*"]

Point the Slack app's Event Subscriptions request URL at {public_base_url}/slack/events and the Interactivity request URL at {public_base_url}/slack/interactions. Subscribe to app_mention, message.im, message.channels, and assistant_thread_started. Every inbound request is HMAC-verified against signing_secret.

Triggering: in channels the bot acts only when explicitly @mentioned; untagged messages are captured as thread context and folded into the next mention. DMs always trigger. Sessions are keyed per thread.

Functions

Messaging — slack::chat::post-message · update · delete · post-ephemeral · schedule-message · get-permalink

Conversations — slack::conversations::list · info · history · replies · create · invite · join · members · open · set-topic · set-purpose · archive

Reactions — slack::reactions::add · remove · get

Files — slack::files::upload (reserve URL → upload bytes → finalize) · info · list

Users — slack::users::list · info · lookup-by-email · profile-get

Views — slack::views::open · publish · update · push

Pins / bookmarks — slack::pins::add · list · slack::bookmarks::add

Search — slack::search::messages (requires user_token)

Assistant — slack::assistant::set-status · set-title · set-suggested-prompts

Admin — slack::auth::test · slack::config-status

Escape hatch — slack::call { method, params, as_user? } calls any Slack Web API method by name, so every method is reachable even before it has a typed wrapper.

Bridge — slack::notify { session_id, text|blocks } reaches the Slack thread bound to a session out-of-band (e.g. a scheduled reminder). slack::events and slack::interactions are the HMAC-verified HTTP ingress endpoints; the slack::on-* functions are internal bindings that stream harness output and post approvals.

Typed functions accept the well-known parameters explicitly and pass any additional Slack parameters through. Each returns the full Slack response payload.

Local development

cargo run -- --url ws://127.0.0.1:49134 --config ./config.collect.yaml
cargo test
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings