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.
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
slacktriggers. - Thread = session. Conversations are correlated by a
session_keyderived from the Slack thread, so follow-ups in the same thread continue the same agent run. - Sender and channel context. The message the agent receives ends with who sent it and where:
user_id,user_name,user_email,channel_id, andthread_ts. Name and email come from Slack'susers.info, and the email needs theusers:read.emailscope; a field Slack does not return is left out. - Replies go through the agent, not the bot. The agent delivers its answer by calling the
reply_to_slack_threadtool, which routes back through the run gateway to theslack-background-agentservice and streams into the thread using Slack's native streaming API. - Runs not started from Slack have no thread to reply to. A run started by a webhook, API call, or schedule on an agent with Slack replies enabled carries no reply token, so
reply_to_slack_threadcannot post. Willow appends a delivery note to those turns telling the agent not to call that tool and to post through its Slack integration's message tools instead, for example by posting to a channel. Give such an agent a Slack integration tool that can post messages if it should report in Slack. - 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 |
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 Build > 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 do not paste a fresh manifest and credentials for every agent.
- Go to api.slack.com/apps > Your App Configuration Tokens > Generate.
- Copy the access token (
xoxe.xoxp-…) and refresh token (xoxe-1-…). - 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.
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 is 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_URLenv var by Helm and is not 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.
Which gateway serves an agent's Slack app
When an agent runs on an external (self-hosted) run gateway and you have registered Slack agent gateways, its Slack app should connect through the Slack agent gateway on the same domain as that run gateway (compared by parent domain, so run.acme.example and slack.acme.example match). Willow chooses it for you when exactly one registered gateway shares the domain, both while you set up the Slack app and when you move the agent onto an external gateway. It never overrides a Slack agent gateway you already chose. You can change the choice under Settings > Slack App > Slack agent gateway.
If the agent's Slack app connects through a gateway on a different domain, or through the Willow default while a same-domain gateway exists, the Slack App section shows a Slack agent gateway on a different domain warning with a button to switch to the matching gateway. Slack events and replies may never reach the agent's network until you do.
Per-agent setup
Each agent that should work in Slack gets its own app. Setup lives on the agent under Settings > Slack App. Channel response rules live separately under Triggers > Channels.
- Create a background agent or open an existing one.
- Open Settings and expand Slack App.
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.withwillow.ai 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 are 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 Slack 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 do not 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.
-
In the agent's Triggers tab, add a Slack trigger.
-
Choose the channels it should listen in (leave empty for any channel the bot is in).
-
Choose whether it fires on any message or only when the agent's bot is @mentioned. With New threads or All messages, the agent stays silent on a message that tags a person but not the agent's bot, because the message is addressed to that person. Turn on Answer when a person is tagged on the channel row to have it answer those too. Posts from a workflow or another bot are not held back this way.
Each row also has Reply in thread, which posts the agent's answer back into the Slack thread. Turn it off to run the agent silently on those messages. With Reply in thread on and the mode set to Mentioned only or New threads, Keep answering in threads it joined appears. Once the agent has replied in a thread, it answers later replies there without another @mention. All messages already answers every thread reply. The agent ignores its own messages. The same settings are on the All other channels and All Direct Messages rows.
-
Optionally narrow a channel row under Conditions: Only from these users (Slack member IDs) and Message matches regex. The regex is a case-insensitive JavaScript pattern matched against the message text and the text of any attachments, so a bot that posts only attachments (such as a CloudWatch alarm) can still match. An @mention of the agent always runs it, even when the message does not match the regex, but Only from these users still applies.
-
Invite the agent's bot to the relevant channels in Slack (for example
/invite @Your Agent). -
Optionally pick a mode for the channel (beta) to run the agent under extra instructions there, and to have it post a structured result.
Reaction triggers
Each channel row and the All other channels / All Direct Messages default rows also accept a list of reaction emojis. When a user adds one of the listed emoji reactions to a message, the agent runs on that message. Reactions are off by default — list at least one emoji name (without colons, for example white_check_mark) to enable them for that row.
Reaction triggers use the reactions:read scope and the reaction_added event, which Willow adds automatically to apps created after this feature shipped. If your agent's Slack app was installed before reaction triggers were available, open Settings > Slack App, select Update app permissions, and reinstall the app in Slack to pick up the new scopes.
Files and voice clips
Images (PNG, JPEG, GIF, WebP) and PDFs attached to a Slack message are passed to the agent, up to 10 files of 5 MB each per message. Voice and video clips recorded in Slack are passed as the transcript Slack generates for them, marked as auto-generated and possibly inaccurate, and capped at 20,000 characters. If Slack has no transcript for a clip (transcription is off, failed, or unsupported for the language) or it is not ready yet, the agent is told the clip was skipped, so resend it after a few seconds. Other audio and video files are skipped, as is anything over the limits above.
Code reaches the agent in three forms. Fenced code blocks you type in a message are always passed along. Slack snippets and plain-text or source files (for example .json, .py, .sql, or .log) are read and added to the message as code blocks, up to 1 MB per file. Each file is cut off at 50,000 characters and one message carries at most 100,000 characters of file content. These files do not count toward the 10-file limit. Files over the limits, and files hosted outside Slack (for example a Google Drive link), are skipped, and the agent is told which ones.
See Create a Background Agent for templates such as Basic Slack Agent.
Rich replies
An agent can answer a Slack thread with a formatted card as well as text: a table, a chart, a few key numbers, or link buttons. Nothing to set up per agent. The agent decides when a card helps, such as a table of failing deploys or a chart of daily errors, and answers with text when it doesn't.
Every card comes with a short text summary above it. The summary is also what the session transcript shows, and what Slack shows where it can't display the card.
A card can hold:
| Part | Limits |
|---|---|
| Headings and text | |
| Key numbers (label and value pairs) | Up to 10 per card |
| A table | One per card, up to 100 rows and 20 columns |
| Charts (bar, line, area and pie) | Up to 2 per card |
| Link buttons and images | https URLs only |
A card also has to fit in 50 Slack blocks. If the agent sends a card that breaks a limit, Willow refuses it and tells the agent what to change, and the agent fixes it and retries in the same run.
Buttons that run the agent again when someone clicks are not supported yet.
If Slack can't show a card, the reply falls back to the text summary, so the user always gets an answer. Willow tells the agent when its card wasn't shown, and the agent can add anything the summary left out. This happens on a workspace where Slack rejects the card, and on a self-hosted slack-background-agent older than the version that supports cards. On hybrid, update slack-background-agent to get cards.
Rich replies don't apply to Snowflake Cortex agents, which can't call tools. A mode with a structured result is a different thing. It returns data you define, to the API or a webhook, and shows it as a fixed message. A card is the agent's own layout of an answer.
Troubleshooting
| Symptom | What to check |
|---|---|
| "Let Willow create it" is disabled | Store Slack app configuration tokens at the org level first (Channels configurations > Slack). |
| Cannot 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. On a self-hosted run gateway, check that the agent's Slack agent gateway is on the same domain as the run gateway; a Slack agent gateway on a different domain warning in Settings > Slack App means it is not. |
| 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. It also skips a message that tags a person but not the bot, unless Answer when a person is tagged is on for that channel. A message that does not match the row's Message matches regex, or comes from someone not listed under Only from these users, is skipped too, and an invalid regex matches nothing. |
| Agent answers the first message in a thread but ignores the replies | In Mentioned only and New threads, replies inside a thread need an @mention of the bot. Turn on Keep answering in threads it joined on the channel row (it shows when Reply in thread is on), or use All messages. |
| Reaction emoji never triggers the agent | Confirm the emoji name is listed (without colons) on the channel row or the default row, and that the app has the reactions:read scope. Apps installed before reaction triggers shipped need Update app permissions followed by a reinstall — see Reaction triggers above. |
| 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. |
Webhook or scheduled run reports reply_token is required, or the reply tool fails | The run was not triggered from a Slack thread, so there is no thread to reply into. Willow tells the agent to stop calling reply_to_slack_thread and post with its Slack integration's message tools. If the agent keeps trying, tighten its instructions so it knows not to reply to the user on those triggers. |
| Agent answers with text only, never a card | The agent chooses whether a card helps, so a short answer stays text. Snowflake Cortex agents always answer with text. On hybrid, check that slack-background-agent is a version that supports cards. |
| Reply shows only a text summary where a card was expected | Slack refused the card, or the bot is too old to show it. Willow falls back to the text. See Rich replies. |
| 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. |