Connect an agent to Slack
Connect your agent to Slack so people can talk to it where they already work. Once connected, the agent appears in your Slack workspace as a bot. Users message it directly or mention it in a channel.
Astropods does this with the slack adapter, which relays each message between Slack and your agent over the Messaging SDK. You enable it in the agent’s configuration, or at deploy time with --adapter slack.
Watch the video for an overview, or follow the procedure below.
Before you start
To complete this guide, you need the following:
- An agent that is already deployed and live. See Deploy an agent if you haven’t deployed one.
- A Slack workspace where you can create apps. You add the bot to a channel there.
- Access to your agent’s configuration in Astropods. You paste the Slack tokens there.
Create and configure the Slack app
Create the app in the Slack workspace where your target channel lives. Set the app’s scopes, Socket Mode, and event subscription with a manifest. Then create an app-level token and install the app.
Create the app from a manifest
- Go to Slack’s Your Apps page and click Create New App.
- Under From scratch, select Paste a manifest and click Continue. Click the YAML tab, then replace the default manifest with the manifest below.
- Select a workspace, then click Next.
- Review the summary and click Create.
The manifest grants these bot scopes: chat:write sends messages, app_mentions:read detects @mentions, and files:read and files:write let your agent read files users attach and send files back. You can remove the two file scopes if your agent doesn’t handle files. See Files in Slack to learn more.
The manifest also turns on Slack’s Socket Mode, which lets your agent communicate with Slack without a public URL, and subscribes the app to the app_mention bot event. Slack delivers no events to your app without that subscription, so a missing one is the most common reason the integration fails with no error.
Create an app-level token
After you create the app, Slack opens its Basic Information page. Scroll to App-Level Tokens and click Generate Token and Scopes. Name the token, add the connections:write scope, and click Generate. Copy the token, which you need later. It starts with xapp-. Click Done to close the dialog.
Install the app
- In the sidebar, click Install App.
- Click Install to your workspace.
- Review the permissions and click Allow.
- On the Installed App Settings page, copy the Bot User OAuth Token. It starts with
xoxb-.
If your workspace requires approval for new apps, click Request to Workspace Install instead. The token appears on Install App after a workspace admin approves the request.
If you add a scope or event after installing, you must reinstall the app for the changes to take effect.
Connect the app to your agent
Add the tokens to your agent's configuration
- In Astropods, click the Agents tab and select your agent.
- In the sidebar, under Configuration, click General.
- Under Messaging interface, click Slack.
- Paste your Slack App Token and Slack Bot Token into the corresponding fields.
- The optional fields below (Actionable Reactions, Allowed Channel IDs, Observe Channel IDs) can be left blank for an initial test. See Configure bot behavior for what each one does.
- Click Redeploy to apply the change. Astropods opens Deployments. Wait about a minute for the status to change from Deploying to Active.
Invite the bot to a channel and test
Installing the Slack app does not automatically add it to any channel. In the channel where you want to use the agent, type /invite @ and the first letters of the bot’s name, such as /invite @my. Select the bot from the list, then send the message.
Then mention the bot. Type @, select the bot from the list, and add a message:
The agent replies in the thread.
Configure bot behavior
The optional fields under Messaging interface control where and how the bot responds. Separate multiple values with commas. Leave a field blank to use its default.
Set Slack variables from the CLI
Astropods stores the Slack settings as three variables. The agent configuration page sets them from its fields when you click Redeploy. To set them from the CLI, pass each one with --var. See ast blueprint for the flags.
SLACK_CONFIG holds the optional fields as keys:
For example, this command restricts the bot to one channel:
Each SLACK_CONFIG value replaces the previous one, so a redeploy that sets it must include every field you want to keep. The value must be valid JSON. The deploy does not check it, and a malformed value stops both Slack and web chat from starting for that agent.
Restrict the bot to channels
Once Allowed Channel IDs is set, the bot replies to a mention or thread reply in any other channel with a notice that the app is not enabled there, and your agent never receives it.
The channel list controls where the bot listens. Who can use the agent is a separate setting: interface access.
To find a channel ID in Slack, open the channel details. The ID is at the bottom of the About tab.
Troubleshoot
If the agent doesn’t reply, check in this order:
- Event subscriptions are enabled in the Slack app (the most common miss).
- The
app_mentionbot event is subscribed, and the app was reinstalled after adding it. - The bot was actually invited to the channel.
- The agent configuration was redeployed after the tokens were added.
Astropods’ agent monitoring page (Agents > Monitor > Networking) can help confirm whether a Slack event reached the agent at all. If no inbound Slack traffic appears after a mention, the issue is on the Slack side (events not enabled, bot not invited) rather than in the agent itself.
Next steps
- Deploy an agent: choose which adapters a deployment enables
- Managing your agents: inspect, update, and control a running agent
- Monitor your agents: add tracing and metrics to a deployed agent