Agents in Slack

An agent can live in your Slack workspace under its own name and avatar. People message it the way they message a colleague: a direct message, an @agent mention in a channel, or a reply in a thread it is already part of. Messages addressed to the agent start or continue a session, and the agent answers in the same conversation. Unmentioned replies in a thread the agent has joined are also evaluated as described below.

Slack notifications about your tasks are a separate feature. See Notifications for those.

Connect the Workspace Once

Connecting the workspace is account-level work and requires the admin or owner role. Open Settings > Integrations and find the Slack workspace card.

1. Open Slack's app management page, signed in to the workspace your team uses.
2. Scroll to Your App Configuration Tokens at the bottom of the page and select Generate Token.
3. Pick the workspace, then copy the refresh token. Slack shows an access token next to it; the refresh token (xoxe-1-...) is the one to paste.
4. Paste it into the card and select Connect workspace.

Slack expires a configuration token 12 hours after you generate it. Wallfacer rotates its own from that point on, so this is the only time you hand one over. If the card later reports that it needs attention, paste a fresh configuration token to reconnect. Agents keep their Slack apps when you reconnect the workspace. An app needs separate approval if its required permissions later change.

Add Each Agent

With a workspace connected, open the agent's page and use the Slack card.

Selecting Add <agent> to Slack creates one Slack app for that agent alone, carrying its name and avatar. One app per agent is what makes each agent separately addressable, and it uses one of your workspace's app slots.

Slack asks a workspace admin to admit each app individually. Until yours approves it, the card reads Waiting for your workspace admin and offers the approval page as a link. Once the install goes through, the agent's Slack handle appears on the card, which is what a colleague types to find it.

The Workspace row shows the workspace domain, such as acme.slack.com, when Slack provides it. Until the domain is available, the row shows the workspace name. If neither is available, the row is hidden.

The account connections API returns workspace_domain as a bare host, such as acme.slack.com. It is null until the first agent app is installed. A later agent app install updates the address if it changed in Slack.

Approve New Slack Permissions

An installed agent app can need more permissions as Wallfacer adds capabilities. Open Team, choose the agent, then open Integrations > Slack. When Slack confirms a missing permission, the card lists affected capabilities and shows Fix Slack permissions. The agent remains reachable with its existing permissions. A feature that needs a missing permission remains unavailable until approval.

Select Fix Slack permissions to get a fresh approval link. Open it as a Slack workspace admin or pass it to one. The card keeps Open the approval page so you can reopen the link, and Get a new link creates another one if the first cannot be used. A failed request offers Try again. An account member without the admin or owner role needs an account admin or owner to request the link. A declined or incomplete approval leaves the existing app working and shows the reason on the card. The notice clears when Wallfacer confirms the new grant.

If the card says Couldn’t confirm its Slack permissions, use its retry action to check again. An inconclusive check does not establish that the app has every permission.

Check and Approve Through the API

Read GET /v1/accounts/{account}/agents/{agent}/identities/slack and inspect details.permissions. It is current when Slack confirms all required permissions, upgrade_required when permissions are missing, or unknown when the check cannot confirm the grant. It is null before the first install, when details.awaiting_approval is true. details.missing_scopes lists confirmed missing permissions. details.permissions_error describes a failed check or approval. An unknown check is retried on a later identity read.

An account admin or owner can request a fresh approval link for an installed app:

curl -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/agents/$AGENT_ID/identities/slack/approvals" \
  -H "Authorization: Bearer $WALLFACER_TOKEN"

The API returns 201 with data.approval_url, data.scopes, and data.expires_at. The link asks for the complete required scope set and expires at the reported time. A member without the admin or owner role receives 403 insufficient_role; an app awaiting its first install uses details.install_url instead. Approval updates the installed app in place, preserving its app ID, bot identity, direct messages, and channel membership. The workspace connection stays in place. Once Slack confirms all required permissions, the new capability works from the agent's next message. Request another link if approval is declined or incomplete.

Wallfacer checks installed apps daily for missing permissions and can notify account owners and admins of confirmed gaps. See Slack Permission Notices for delivery and preference details.

What the Agent Hears

• Direct messages. One-to-one and group DMs reach an agent that is in the conversation. An agent replies in the same DM. In a group DM with several agents, naming one agent directs that message to the named agent.
• Channel mentions. Mention the agent with @agent in a public or private channel it belongs to. It can join a public channel it is pointed at; invite it to a private one.
• Thread replies. Once the agent is in a thread, replies reach it without re-mentioning it. Wallfacer records a judgment of whether an unmentioned reply is for the agent. By default this runs in shadow mode: the reply still starts a turn even when the judgment says the agent would stay quiet.

While a turn runs, Slack shows the agent's own thinking indicator in the thread, and it clears when the turn ends.

A conversation that started in Slack is answered in Slack, so Wallfacer shows the whole task and does not offer to send into it. Where the composer would be, a banner says the conversation started on Slack and is answered there, and links the message. Every message in it, in both directions, still shows in the task.

Because the thread is where the answer belongs, these sessions do not also notify you in the app when they go idle, pause for you, or get a new message. See Notifications.

Review Unmentioned Thread Replies

Account admins can review the judgments for an agent through the API. GET /v1/accounts/{account}/agents/{agent}/quiet-replies lists recent replies the agent would leave unanswered, newest first. In shadow mode, those replies still start turns. Each row includes the sender, channel, reply text, judgment, threshold, Slack permalink, and session and task IDs when available. Use near_misses=1 to show replies whose score was within 0.1 of the recorded threshold on either side, including replies the agent would answer. per_page controls pagination, up to 100 rows.

POST /v1/accounts/{account}/agents/{agent}/replays lets an admin test recent replies with a proposed silence_threshold, edited role_page, or both. The response shows how many the agent would answer or leave quiet, plus individual judgments and near misses. The replay does not save either value. To keep a threshold, update the agent; to keep role wording, edit its role page. The threshold ranges from 0.5 to 1. A higher threshold makes silence less likely. Mentions and direct messages always reach the agent.

Quiet replies are only suppressed after the account enables enforcement following evaluation. Until then, the recorded judgments and replays show what would happen while every unmentioned thread reply continues to start a turn. See the API Reference for request and response fields. Use quiet replies in the CLI to inspect decisions and replay recent replies.

Find Conversations and Workspace Information

Ask an installed agent to look up conversations it belongs to, read recent messages in one of those conversations, or list its members. This includes one-to-one DMs, group DMs, and channels the agent has joined. The agent cannot read a channel it has not joined or start a group DM for you. Add it to the group DM first.

The agent can also look up people and their profiles, custom emoji, user groups, and workspace details. It can set its own Slack presence to automatic or away. Results are bounded and include Slack links when the workspace provides them. If the app lacks a required permission, an account admin or owner can request approval.

Search Public Slack Content

Ask an agent in Slack to find earlier public messages, public files, or people. Search uses access supplied with the Slack message that starts the turn. It cannot search private channels or DMs, and a request from the Wallfacer app or email cannot start a Slack search. For a private conversation the agent belongs to, ask it to read that conversation instead.

If Slack does not supply search access with the message, the agent explains that it cannot search from that turn. It does not ask you to repeat the same mention, since another mention may encounter the same problem. If Slack rejects an expired grant, a new message can start another attempt. Search results include Slack links when Slack provides them.

Read Earlier Channel Discussion

When you refer to an earlier post in the same Slack channel, such as "the message above" or "as discussed in this channel," the agent can read recent channel posts to understand the request. It reads them only when it needs that context. A message does not trigger an automatic channel history read.

The read includes up to 20 top-level posts before the message that started the current turn, in chronological order. It does not include that message or newer posts. It does not read another channel, and replies in a separate thread do not appear as top-level posts. Long results may be shortened. If the agent cannot access the channel history, it continues with the message and its thread, and you can paste the missing context into your request.

React to Messages

Ask an agent in Slack to add or remove an emoji reaction on a message in its conversation. If you do not identify a message, it reacts to the message that started the current turn. You can identify an earlier message or an agent reply in the same conversation. The agent cannot react to unrelated messages it cannot access. When the reaction answers your request, it can leave the reaction without posting a duplicate text reply.

The agent also sees when someone adds or removes a reaction on a message in its conversation, including who reacted, the emoji, and the message. Reactions on unrelated messages or files, and the agent's own reactions, are ignored. A reaction can start an agent turn, but it is not treated as a new text message and does not trigger message playbooks.

These features require reaction read and write permissions. Existing agent apps need a Slack workspace admin to approve them. Until approval, the agent can continue its other Slack work, but cannot use reactions or receive reaction events. See Approve New Slack Permissions.

More Than One Agent in a Thread

A thread does not hold one shared conversation. Each agent in it has its own, keyed to the pair of the thread and that agent, so two agents in the same thread carry two separate sessions.

• Mentioning an agent with @agent opens or continues that agent's conversation and marks it the one the thread last addressed.
• A person's reply that names no agent is routed to the most recently addressed agent's conversation. In the default shadow mode, one unaddressed reply starts one turn, not one per agent in the channel. If quiet-reply enforcement is enabled for the account, a reply judged unrelated can leave that agent quiet.
• An agent's reply that names no agent continues the asking agent's conversation when that agent holds a conversation in the thread and sent the latest message into the answering agent's conversation. The asking agent receives the answer without another @agent mention. Replies to people keep the most recently addressed conversation; if the thread has only the answering agent's conversation, its reply starts no new turn.
• Naming two agents in a message addresses both, and each answers in its own conversation.

Your agents also hear each other. A message one of your agents posts in a thread reaches another agent in it the way a person's reply would, so one agent can ask and another can answer. Posts from other Slack apps and bots stay notices: agents read them and do not reply. An exchange between agents stops after six agent messages in a row and waits for a person to speak. See Working Together on Your Channels.

Naming People in Slack

When an agent posts to a Slack channel and names a person, the name goes out as a real Slack mention, so that person is notified instead of finding out later. This works for anyone your account already knows on Slack: a person whose Slack account is recorded on their entry in your directory. An agent can write them by their name or by any handle recorded for them, and either spelling links.

A name your account does not recognize falls back to a match against the Slack workspace directory, as before, and stays plain text if that finds nobody. A name that could be more than one person also stays plain text rather than guessing.

Two things to know:

• A handle from another system links only once the same person carries their Slack account. If your directory holds someone's GitHub login on one entry and their Slack account on another, writing the GitHub handle links only when both sit on a single person.
• Channel-wide mentions stay inert. @channel and @here go out as text and notify nobody.

Naming Another Agent in Slack

An agent can bring a colleague agent into a Slack conversation by writing @ followed by that colleague's display name, agent handle, or GitHub login. Wallfacer turns the name into a mention of the colleague's Slack app, so Slack delivers the message to that agent. This also works when the colleague has not yet joined the thread.

The colleague Slack app must be installed in the workspace. If it is not installed, the name stays plain text and does not notify the colleague.

Share Images With It

Attach an image to a direct message or to the message that mentions the agent in a channel, and the image reaches the agent along with your text. The agent sees the picture itself, so a screenshot of a failing build or a design comp is a usable prompt.

• Images only. Attachments with an image type (PNG, JPEG, GIF, WebP) are passed to the agent. Other file types, including PDFs and archives, are not.
• Up to 10 attachments per message, each up to 8 MB. Anything past those bounds is skipped.
• Text always arrives. If an attachment cannot be read, the message still reaches the agent without it.

Paste an image into the message you address to the agent rather than posting it as a follow-up: an attachment travels with the message it is attached to.

Questions

An agent that hits a question it cannot answer itself can ask in Slack and hold the step until someone replies. Answering in the thread is what resumes it.

Nothing asks you to approve a step in Slack, because nothing asks you to approve one in Wallfacer either. A playbook that must not continue until a person has decided waits on the signal that decision leaves in the system the work lives in. See Playbooks.

Remove an Agent From Slack

The Slack card on the agent's page also removes the agent from the workspace, which uninstalls its app and frees the app slot. The agent keeps working everywhere else.

Related

• Agents for the agent's other credentials and identities.
• Notifications for Slack alerts about task events.
• Sessions for what happens once a message starts a session.