Slack
A Slack agent answers when someone mentions it or sends it a DM. It replies in a thread, and every follow-up in that thread continues the same session. While it works, the thread status shows what it's doing, and approvals and questions appear as buttons. Set up creates the Slack app and connects it through Vercel Connect.
For information on all configuration and customization options, see the Slack reference.
Set up
Run the guided setup from your agent project, then deploy:
Setup signs you in to Vercel, links a project, creates or reuses a Slack app through Vercel Connect, asks you to install it in a workspace, and writes the channel file:
Connect keeps the bot token, token rotation, workspace installations, and request verification out of your project. If setup stops partway, run eve add channel/slack again; it runs only the missing steps. To route a preview branch to its own Slack app, see Test a preview branch.
Run eve add channel/slack and choose Use portable credentials. eve writes a channel file that reads SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET, but doesn't create the Slack app:
- Add the
app_mentions:readandchat:writebot scopes, pluschannels:history,groups:history,im:history, andmpim:historyfor DMs and message edits,files:readfor inbound files, andfiles:writefor long replies. - Install the app. Set
SLACK_BOT_TOKENto its Bot User OAuth Token andSLACK_SIGNING_SECRETto the signing secret from Basic Information, in.env.localand in your host's environment. - Set
https://your-agent.example/eve/v1/slackas the Request URL under Event Subscriptions (subscribe toapp_mention, plusmessage.channels,message.groups,message.im, andmessage.mpimfor DMs and message edits), Interactivity & Shortcuts, and each Slash Command.
Portable credentials also work on Vercel when you manage the Slack app yourself.
Default channel behavior
By default, the agent answers @mentions in any channel it has joined, replying in a thread under the message. Each thread is one session, so people continue the conversation by mentioning the agent again in that thread. It also answers DMs once the Slack app has the message.im event and im:history scope. While it works, the thread status shows what it's doing.
- To customize what happens on a mention or DM, override
onAppMentionoronDirectMessage. See Message hooks. - To answer thread replies without a mention, see Reply without a mention.
- To control what happens when someone edits a message, see Handle message edits.
- To change the thread status or what the agent posts, see Delivery and Customize rendering.
Reply without a mention
Return { auth } from onMessage to start a turn, or null to ignore the message. This hook answers mentions, code channel messages, and DMs. It also follows threads the agent already serves, and lets the agent decide whether each reply without a mention is meant for it:
Add the no_reply tool so the agent can stay quiet when a reply isn't meant for it:
- Without
onAppMentionandonDirectMessage, mentions and DMs reachonMessagetoo, so the hook answers them first. It checkschannel_typebecausectx.isDMOrPrivateChannel()is alsotruein private channels. ctx.isSubscribed()istrueonce the thread has a session, so the agent follows only threads it was brought into. Top-level messages still need a mention.ctx.editis set for an edit, which only reaches a thread that has a session. The hook follows it like a reply, including an edit to the thread's first message.status: "deferred"shows no thread status until the agent calls a tool, so a reply the agent ends withno_replyleaves no trace in the thread.guidancetells the model how to treat this one message. See Status and guidance.defaultSlackAuthgives each Slack user their own identity, so by default only the person whose message led to an approval can answer it. With{ auth: null }, messages carry no identity, and anyone in the thread can answer it.- A reply from the person a pending question or approval is waiting on can still answer it, even when the reply is meant for someone else, because eve matches answers by identity before the model sees the message.
Slack sends un-mentioned channel messages only when the app subscribes to them:
In the Connect connector's Advanced settings, add message.channels under Trigger Event Types and channels:history under Bot Scopes. For private channels, also add message.groups and groups:history.
In Slack app settings, subscribe to the message.channels event and add the channels:history bot scope. For private channels, also add message.groups and groups:history. Then reinstall the app.
To join new conversations too, add a decision model with decide after the checks that cost nothing. This hook answers addressed messages and followed threads without a model call. It asks decide about other messages in the channels you choose, and ignores the rest:
An ignored message never starts a turn. Once decide lets a message through, its thread has a session, so later replies take the followed-thread branch without another decision call. If decide throws, eve drops the message; catch the error and return { auth } to answer anyway. See Classify ambient replies with a decision model for choosing the decision model.
For a fuller setup with per-channel goals, instructions for staying silent, a decision model that filters out clearly unintended messages, and monitoring, see Ambient Listening in Slack.
Handle message edits
When someone edits a DM, a code channel message, or a message that mentions the agent before or after the edit, in a thread the agent already serves, eve sends the edit to that session. The model sees a diff of the changed lines and the full edited message. By default, the edit joins a running turn. If the agent already replied, the edit starts a new turn, which shows no thread status until its first tool call finishes.
Add the no_reply tool so the agent can stay quiet when an edit changes nothing, and say when to use it in your instructions:
If you set onAppMention, onDirectMessage, or onMessage, eve runs the edited message through the hook a new message of the same kind would reach, so your checks apply to edits too. With the hook in Reply without a mention, an edit to a followed reply reaches the agent with the same guidance. ctx.edit is set while a hook decides an edit, so a hook with side effects, such as ctx.send() or a decision model call, can skip them for edits. To decide edits yourself, set onMessageEdited. Return { auth } to send an edit, or null to drop it. This one sends every edit in a thread the agent serves:
Slack sends edits only to apps subscribed to the message.channels, message.groups, message.im, and message.mpim events, with the matching *:history scopes. With Vercel Connect, add message.mpim and mpim:history to the connector for group DMs; its defaults include the rest. See Message edits for the model format.
Load prior thread messages
By default, the agent sees only the message that mentioned it. Set threadContext to also load the thread's earlier replies, each attributed to its Slack user. With since: "last-agent-reply", each mention adds only what's new since the agent last replied:
Provide agent with user info
The agent sees each sender's Slack user ID. To also give it their name, and optionally their email, set messageContext.users:
This adds the users:read scope, plus users:read.email with email: true, so reinstall the Slack app after enabling it. It's off by default because names and emails then reach model context, session history, and traces. See Add sender names and emails for caching and custom lookups.
Human-in-the-loop interactions
By default, tool approvals and questions from ctx.ask() appear in the thread as buttons and selects. Once someone answers, the card shows the answer and who gave it. When a tool needs a connection the person hasn't authorized, the sign-in link goes to them in an ephemeral message, and the thread shows a status without the link.
To show a request only to the person who started the turn, return "ephemeral" from approvalChannel to keep it in the thread, or "direct-message" to send it to their DM:
- To require approval for a tool or ask the person a question, see Human-in-the-loop.
- To control who can answer, add
onAnswers. See Restrict access. - To change how approval and question cards look, see Restyle approval and question cards.
Start conversations proactively
Send to the Slack channel from a schedule, a tool, or another channel's route. A { channelId } target starts a new thread, and initialMessage posts its root before the agent runs:
Teammates continue the session by mentioning the agent in that thread. Add threadTs to the target to continue an existing thread instead.
Handle slash commands
onSlashCommand receives commands configured under Slash Commands in your Slack app. eve acknowledges the command right away and keeps your handler running:
Use onShortcut for message and global shortcuts, onInteraction for your own buttons, and onEvent for other Events API events such as team_join.
Enable code channels
A Slack code channel is a channel dedicated to one agent task. With codeChannels: true, the agent answers every message in a code channel without a mention, and the whole channel is one session:
To let the agent move multi-step work out of a thread, give it a tool that calls openCodeChannel(). The new channel starts with the conversation so far:
Code channels need extra Slack app permissions:
Turn on Code Channels in the connector's settings, which adds the code_channels:manage scope and the message.session and agent_session_stopped events. Then add groups:read and mpim:read under Bot Scopes.
With codeChannels: true, the generated app manifest includes everything code channels need. If you configure the app by hand in Slack app settings, enable code channels, add the code_channels:manage, channels:history, channels:read, groups:history, groups:read, im:read, and mpim:read bot scopes, and subscribe to the message.session and agent_session_stopped events. Then reinstall the app.
See How eve serves code channels for replies, status, and hooks in a code channel.
Customize rendering
Renderers change what the agent posts without replacing eve's defaults. Each handler calls next() to run eve's default. This one adds a note below each final reply:
Renderers can also restyle the task card and approval cards. See Customize rendering.
Handle file attachments
Images, PDFs, audio, and other files attached to a message reach the agent. When a mention has no files, eve also collects files posted in the thread since the agent's previous mention. Downloads need the files:read scope. See Attachments for limits.
Restrict access
A valid Slack signature proves the event came from Slack, not that the sender should reach your agent. Slack Connect can deliver events from people outside your workspace. To allow only certain people, check them in every inbound hook you enable, and in onAnswers so nobody else can click an approval:
Keep authorization checks inside sensitive tools too. The reference adds per-conversation allowlists.
Reference
The Slack reference covers:
- Setup: portable credentials, preview branches, a different Slack API host, and troubleshooting
- Inbound hooks: handler order, sender profiles, decision-model replies, session operations on
ctx, ending a conversation, and Events API callbacks - Code channels: detection, privacy, and building your own code channel tool
- Delivery: the thread status, task card, renderers, and reply fallbacks
- Human-in-the-loop: approval cards, sign-ins, and HITL helpers
- Cards, proactive targets, attachments, and audience