Slack agent

Run the same agent as in-app Ask from Slack mentions and DMs, including tools, MCP connectors, approvals, and shared thread history.

The Slack bot is the SpeakerWeave agent, not a separate assistant. A mention or DM enters the same agent/service.run_turn runtime as in-app Ask, with the same organization-scoped tool registry, connected MCP servers, provider, thread store, and permission gate.

That means you can start a conversation in Slack, approve a sensitive action without leaving Slack, and find the persisted thread later in the in-app Ask history.

The app registers as a Slack Agent (the AGENT badge): it gets Slack’s split-pane chat surface with suggested prompts, a native “is thinking…” status line while a turn runs — in the pane and in channel threads — and a New chat control that starts a fresh agent conversation (assistant_thread_started resets the thread mapping).

How the bridge works

Slack mention or DM
        ↓ signed event
/api/slack/events
        ↓ Slack transport
agent/service.run_turn
        ↓
same provider runtime + tool registry + MCP connectors
        ↓
one final Slack reply + persisted Ask thread

Slack acknowledges Events API requests immediately and finishes the agent turn in the background. The bridge converts the final answer to Slack mrkdwn and posts it once. Slack delivery failures are logged without undoing the persisted agent turn.

The in-app Ask panel is an SSE adapter over run_turn; Slack is an Events API and Interactivity adapter over that same function. Neither transport owns a second prompt, model loop, or tool list.

Approvals in Slack

When the agent reaches a permission-gated action—such as sending email, recording a decision, publishing, deleting data, or calling a mutating MCP tool—it posts an Approval needed card with Approve and Deny buttons.

The turn waits for up to 300 seconds. Clicking either button resolves the same permission gate used by in-app Ask, then replaces the card with a terminal approved or denied state. If the request was already handled or expired, Slack says so and does not execute the action.

The approval button value contains only an opaque request ID. Keep Interactivity pointed at the signed SpeakerWeave endpoint; do not put tool arguments or credentials in Slack action values.

Threads and identity

SpeakerWeave stores the Slack-to-agent relationship in slack_agent_threads:

Slack conversation	Agent behavior
Channel mention	Creates or resumes the mapping for that channel thread and replies in the Slack thread
Reply in a channel thread	Resumes the same agent thread
Top-level DM	Resumes the most recent agent thread for that DM channel, or creates one; replies stay unthreaded
Agent pane conversation	Each pane chat is a threaded DM mapped to its own agent thread; replies stay inside the pane
New chat in the pane	assistant_thread_started inserts a fresh mapping, so the next message starts a new agent conversation

Channel messages are attributed with the sender’s Slack display name when users.info is available. Agent threads use slack:<user_id> as their user identity, remain organization-scoped, and appear in the in-app Ask thread history.

Set up the Slack app

The manifest does almost all of the configuration. For a self-hosted deployment, first replace both https://speakerweave.com request URLs in the manifest with your public web origin.

1. In Slack, choose Create New App → From an app manifest and paste api/slack_manifest.json (or copy the manifest from Settings → Integrations in the app). The manifest configures:
   • Bot token scopes: app_mentions:read, assistant:write, chat:write, im:history, im:read, im:write, users:read
   • Bot events on /api/slack/events: app_mention, assistant_thread_started, message.im
   • Interactivity on that same URL (this is what delivers Approve/Deny clicks)
   • The agent view (AGENT badge + split-pane surface) with a description and suggested prompts
   • An unlocked messages tab, so the pane composer accepts messages
   • Socket Mode off — SpeakerWeave receives signed HTTPS events only
2. Install the app to the workspace and copy the Bot User OAuth Token (xoxb-…) from OAuth & Permissions and the Signing Secret from Basic Information.
3. Optional but recommended: upload the app icon from assets/slack-app-icon-1024.png under Basic Information → Display Information.
4. Invite the bot to any channels where it should answer mentions (/invite @SpeakerWeave). DMs and the agent pane need no invite.
5. Configure the API environment (next section) and send the bot a DM.

If you change scopes or events later, Slack requires a reinstall before the new configuration takes effect; the token value survives reinstalls.

Configure the API environment

Variable	Purpose
SLACK_SIGNING_SECRET	Verifies the raw body of Events API and Interactivity requests
SLACK_BOT_TOKEN	Slack bot token (xoxb-…) used to read display names and post replies
SLACK_DEFAULT_ORG	Organization that this Slack workspace is allowed to access; defaults to org_dev
OPENAI_API_KEY or ANTHROPIC_API_KEY	Enables the selected agent provider; ASSISTANT_PROVIDER can choose explicitly

You can verify the detected provider and key state under Settings → Integrations → Slack bot.

Troubleshooting

Symptom	Cause and fix
”Sending messages to this app has been turned off”	The messages tab is locked. App Home → Show Tabs → Chat/Messages Tab must be on with Allow users to send … messages checked. Apps created from the current manifest have this preconfigured.
No AGENT badge / no split pane	The agent designation isn’t active: check the Agents page in the Slack app config, then reinstall. Slack clients cache app metadata — fully reload Slack (Cmd+R) after changing it.
Approve/Deny buttons do nothing	Interactivity is off or points at a different URL than Event Subscriptions. Both must be the same signed /api/slack/events endpoint.
No “is thinking…” status	The status renders only inside threads (the agent pane or a channel thread), requires the assistant:write scope, and the app must be reinstalled after adding it.
Bot never replies in a channel	The bot must be a member of that channel. Also confirm the events request URL shows Verified in Event Subscriptions.
Replies lack sender names in shared channels	users:read is missing or the app wasn’t reinstalled after adding it.

Deployment boundary

The reference configuration intentionally binds one deployment to one Slack workspace and one SLACK_DEFAULT_ORG; there is no Slack OAuth installation flow. Before serving multiple workspaces from one deployment, add a workspace-to-organization installation table and resolve the organization from the verified Slack workspace instead of a global environment value.