Set up Slack for background agents

Background agents can listen in Slack channels, start when a configured trigger fires, and stream their response back into the thread. Each agent runs as its own dedicated Slack app (its own bot identity, its own connection) — separate from Willow's notification bot and separate from every other agent.

At the org level you store a small amount of shared configuration once; the actual Slack app is created and installed per agent.

What changed

Earlier versions used a single org-wide "Willow Agent" Slack app that you connected to your workspace once. Willow now provisions one Slack app per background agent. Org settings only hold reusable app-configuration tokens (and, on hybrid, the gateway URLs of your slack-background-agent services). There is no longer a "Working message" field — agents show Slack's native "is thinking…" status while they run.

How it works

The slack-background-agent service is the bridge between Slack and your agents. It holds one connection per agent, matches incoming events against that agent's Slack triggers, delivers the message through the run gateway, and streams the agent's reply back into the thread.

Key points:

• Per-agent connection. The Slack connection is the agent — routing only considers that agent's own enabled slack triggers.
• Thread = session. Conversations are correlated by a session_key derived from the Slack thread, so follow-ups in the same thread continue the same agent run.
• Replies go through the agent, not the bot. The agent delivers its answer by calling the reply_to_slack_thread tool, which routes back through the run gateway to the slack-background-agent service and streams into the thread using Slack's native streaming API.
• Two ingress modes. An agent's Slack app can receive events over Socket Mode (outbound WebSocket, no public URL) or the HTTP Events API (Slack POSTs to Willow's public /api/slack/events).

Deployment topologies

What you configure depends on how Willow is deployed.

Deployment	Where slack-background-agent runs	What you configure
SaaS	Willow-hosted	Store app-configuration tokens (optional, enables one-click app creation), then create and install a Slack app per agent
Hybrid	Willow-hosted or your own instances in your cluster	If self-hosting: set the Slack agent service URL (required) and, only if running more than one instance, register additional named gateways. Then store app-configuration tokens and create/install a Slack app per agent
On-prem	Your cluster	Service URL is set by your deployment (SLACK_BG_AGENT_URL); store app-configuration tokens, then create and install a Slack app per agent

note

Hybrid means your organization uses an external run gateway (MCP traffic runs in your infrastructure while the admin UI stays on Willow SaaS). On hybrid you can let Willow host the Slack agent service or run your own. On-prem means the full Willow stack runs in your environment.

Org-level setup (once)

Open Manage > Machine Users > Background Agents, select the gear icon (Settings), and find the Channels configurations card at /manage/background-agents/settings. On the Slack row, select Set up (or Manage) to open the dialog.

Store Slack app configuration tokens

App-configuration tokens let Willow create each agent's dedicated Slack app for you (the "Let Willow create it" option below), so you don't paste a fresh manifest and credentials for every agent.

1. Go to api.slack.com/apps > Your App Configuration Tokens > Generate.
2. Copy the access token (xoxe.xoxp-…) and refresh token (xoxe-1-…).
3. Paste both into the Slack dialog and save.

Willow stores them encrypted and auto-refreshes them, so they stay valid for future agents. The org row shows Configured once tokens are stored.

If you prefer to create each app by hand, you can skip this step and use Create it yourself when setting up an agent.

Set the service URL (hybrid, self-hosted only — required)

If you run your own slack-background-agent instance (hybrid), set Slack agent service URL in the dialog to that instance's reachable URL and save. For how to deploy it, see Slack Background Agent in the Hybrid Deployment guide.

Required if you self-host, even with a single instance

This is not optional. Without it stored, db-service still treats your org as SaaS-hosted, so Willow's shared platform-wide instance keeps claiming your un-pinned agents' Socket Mode connections instead of leaving them to your own instance. It's independent of the named gateways below — set it even if you only ever run one self-hosted instance and never touch gateways.

• SaaS: not needed — agents use Willow's hosted service.
• On-prem: the in-cluster service URL is injected via the SLACK_BG_AGENT_URL env var by Helm and isn't edited here.

Register additional gateways (hybrid, more than one instance only)

If you run more than one self-hosted slack-background-agent instance for this org, register each extra one in the Slack agent gateways section of the dialog with a name and its reachable URL. When you set up an agent you can then pin it to a specific gateway.

Each saved gateway shows its Gateway ID with a copy button. Paste that id into the corresponding deployment's Helm values as deployments.slack-background-agent.gatewayId (injected as GATEWAY_ID) — that deployment then only opens a connection for agents pinned to this gateway. A single default deployment (the one pointed at by the service URL above) needs no gatewayId.

Per-agent setup

Each agent that should work in Slack gets its own app. Setup lives on the agent, in the Slackbot App section (shown in the agent's Triggers tab, and as a post-create step for the Basic Slack Agent template).

1. Create a background agent or open an existing one.
2. Open the Triggers tab and find the Slackbot App section.

Step 1: Choose how events are delivered

Mode	When to use	Requires
Socket Mode	No public URL available; simplest for on-prem/customer VPC	An app-level token (xapp-, scope connections:write)
HTTP Events API (webhook)	Willow admin URL is publicly reachable	A signing secret; Slack POSTs events to /api/slack/events

Step 2: Create the Slack app

• Let Willow create it — uses the org's app-configuration tokens to create an app named after the agent, set its icon, and fill in the credentials automatically. (Requires the org-level tokens above.)
• Create it yourself — open Slack's app-creation flow with Willow's manifest pre-filled (name, bot scopes, ingress mode, OAuth redirect), then paste the credentials back.

The manifest includes the OAuth redirect URL for your environment:

{AUTH_URL}/api/slack/oauth/agent-app/callback

{AUTH_URL} is your Willow admin URL (for example https://your-org.mcp-s.com on the SaaS control plane, or your on-prem hostname).

Bot scopes required (included in the manifest):

app_mentions:read, channels:history, channels:join, channels:read,
groups:history, groups:read, chat:write, chat:write.customize,
users:read, users:read.email

If you're using Socket Mode and creating the app yourself, also generate an app-level token: in the Slack app, open Settings > Basic Information > App-Level Tokens > Generate Token and Scopes, add the connections:write scope, and copy the xapp- token.

Step 3: Save credentials and install

Paste the agent's credentials into the Slackbot App section:

Credential	Needed for
Client ID	Always
Client secret	Always
App token (xapp-)	Socket Mode
Signing secret	HTTP Events API

Then select Install to Slack and complete the OAuth install. The workspace bot token is stored (encrypted) on the agent — you don't paste it. After a successful install the section shows Connected with your Slack team name.

On hybrid with registered gateways, pick which slack-background-agent gateway serves this agent before installing.

Add Slack triggers to an agent

Installing the app lets the agent connect to Slack; triggers decide when it runs.

1. In the agent's Triggers tab, add a Slack trigger.
2. Choose the channels it should listen in (leave empty for any channel the bot is in).
3. Choose whether it fires on any message or only when the agent's bot is @mentioned.
4. Invite the agent's bot to the relevant channels in Slack (for example /invite @Your Agent).

See Create a Background Agent for templates such as Basic Slack Agent.

Troubleshooting

Symptom	What to check
"Let Willow create it" is disabled	Store Slack app configuration tokens at the org level first (Channels configurations > Slack).
Can't install / Install to Slack missing	Save the required credentials first — Client ID + Client secret, plus the app token (Socket Mode) or signing secret (HTTP Events API).
OAuth fails with redirect_uri mismatch	The redirect URL in Slack must exactly match {AUTH_URL}/api/slack/oauth/agent-app/callback. Recreate the app from the manifest if your AUTH_URL changed.
Agent never receives events (Socket Mode)	Confirm Socket Mode is on and the xapp- app token is saved. Ensure slack-background-agent is running and can reach db-service.
Agent never receives events (HTTP)	Confirm the signing secret is saved and Slack can reach your public /api/slack/events.
Agent connected but stays silent	Check the trigger's channel and @mention filters, and that the bot is invited to the channel. With no matching trigger the agent intentionally stays silent.
Reply never appears / status shimmer hangs	The agent must call reply_to_slack_thread to deliver its answer. Confirm the run gateway can reach the slack-background-agent service's /agent-reply endpoint.
Awaiting approval forever	A Slack workspace admin must approve the app install under Slack's app-management settings.
Same message handled twice	An agent with its own dedicated app should not also rely on a legacy org-wide app; only one connection should own the event.

What to do next

• Background Agent Settings
• Create a Background Agent
• Background Agents reference