Connect the Willow Agent Slack app

The Willow Agent is a separate Slack app from Willow's notification bot. It listens in Slack channels, starts background agents when configured triggers fire, and posts responses in the thread.

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

What you see depends on how Willow is deployed:

Deployment	Slack app	What you configure
SaaS	Willow hosts the shared Slack app	Connect your workspace only
Hybrid	Willow-hosted app or your own app running against slack-background-agent in your cluster	Recommended: connect workspace. Your own app: set the service URL, save credentials, connect workspace
On-prem	Your organization runs slack-background-agent in your cluster	Set the service URL, save credentials, connect workspace

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 still use the Willow-hosted Slack app (the Recommended option) or run your own. On-prem means the full Willow stack runs in your environment.

SaaS: connect in one step

When Willow hosts the Slack app, no Slack developer setup is required.

1. Open Background Agent Settings and open the Channels card.
2. On the Slack row, select Set up, then Connect workspace.
3. Approve the install in Slack. If your workspace requires admin approval, the status shows Awaiting approval until an admin approves.

Willow stores the workspace bot token encrypted in your organization settings. Disconnect anytime with Disconnect in the same dialog.

On hybrid, this same one-click flow is available as the Recommended option in the setup dialog — you don't have to run your own Slack app unless you want to.

Hybrid and on-prem: run your own Slack app

When the Slack agent runs in your cluster, each organization needs its own Slack app with Socket Mode and OAuth credentials stored in Willow. In the setup dialog, choose Your Slack app (on hybrid this is the second tab next to Recommended).

Willow generates an app manifest with your deployment's OAuth redirect URL already filled in. Use it to create the app in Slack, then paste the credentials back into Willow.

Step 1: Set the Slack agent service URL

The Slack agent service URL is the base URL of the slack-background-agent service that serves your organization (Socket Mode + reply delivery).

• Hybrid: required. Set it to where your slack-background-agent is reachable before saving credentials or connecting — the Willow-hosted default cannot reach your cluster.
• On-prem: set it to your in-cluster service (this is typically injected via the SLACK_BG_AGENT_URL env var by Helm).
• SaaS: not shown — Willow uses its hosted service automatically.

This is a dedicated field for the Slack agent and is separate from the run gateway used for agent execution. The OAuth redirect in the manifest still uses your Willow admin URL, not this address.

Step 2: Create the app from the manifest

In the Your Slack app tab, select Create app in Slack — this opens Slack's app creation flow with Willow's manifest pre-filled (name, bot scopes, Socket Mode, redirect URL).

The manifest includes the OAuth redirect URL for your environment:

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

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

tip

Slack also accepts a shareable link of the form https://api.slack.com/apps?new_app=1&manifest_yaml=…. Willow's Create app in Slack button builds this URL for you.

Step 3: Create an app-level token (Socket Mode)

Socket Mode is enabled in the manifest, but Slack still requires an app-level token:

1. In your new Slack app, open Settings > Basic Information.
2. Under App-Level Tokens, select Generate Token and Scopes.
3. Add the scope connections:write.
4. Copy the token — it starts with xapp-.

Step 4: Copy OAuth credentials

From the same Slack app:

Slack field	Willow field
Basic Information > App Credentials > Client ID	Client ID
Basic Information > App Credentials > Client Secret	Client secret
App-level token from Step 3	App token (xapp)

Under OAuth & Permissions, confirm the redirect URL matches the one shown in Willow settings (it should already be present if you used the manifest).

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

Step 5: Save credentials and connect

1. Paste App token, Client ID, and Client secret into the Your Slack app tab in the setup dialog.
2. Select Save credentials.
3. Select Connect workspace and complete the OAuth install in Slack.

After a successful install, the Workspace row shows Connected with your Slack team name.

Working message

Optional: set Working message in the setup dialog. This placeholder text is posted in Slack while an agent runs. Leave it empty to use the default.

Add Slack triggers to an agent

Connecting the Slack app only installs the bot into your workspace. To run agents from Slack:

1. Create a background agent (or open an existing one).
2. Open the Triggers tab.
3. Add a Slack trigger and choose channels (or mentions) that should start the agent.

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

Troubleshooting

Symptom	What to check
Can't save credentials / connect (hybrid)	Set the Slack agent service URL first — it's required on hybrid before custom credentials are accepted.
Connect workspace is missing (hybrid/on-prem)	Save all three credentials first (xapp, client ID, client secret).
OAuth fails with redirect_uri mismatch	The redirect URL in Slack must exactly match Willow settings. Recreate the app from the manifest if your AUTH_URL changed.
Bot never receives events	Confirm Socket Mode is on and the xapp- token is saved. Ensure slack-background-agent is running at the configured service URL and can reach db-service.
Awaiting approval forever	A Slack workspace admin must approve the app install under Slack's app management settings.
SaaS org sees hybrid setup UI	The Your Slack app option appears only when the org uses an external run gateway or runs on-prem. Pure SaaS orgs see the one-click Willow app flow only.

What to do next

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